<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Chapter 10 Character Sets, Collations, Unicode</title>
<link rel="stylesheet" href="mvl.css" type="text/css" />
<meta name="generator" content="DocBook XSL Stylesheets + chunker.py v1.9.2" />
<link rel="start" href="index.html" title="{book-title}" />
<link rel="up" href="" title="" />
<link rel="prev" href="language-structure.html" title="Chapter 9 Language Structure" />
<link rel="next" href="data-types.html" title="Chapter 11 Data Types" />
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<div class="navheader">
<table width="100%" summary="Navigation header">
<tr>
<th colspan="3" align="center">Chapter 10 Character Sets, Collations, Unicode</th>
</tr>
<tr>
<td width="20%" align="left"><a accesskey="p" href="language-structure.html">Prev</a> </td>
<th width="60%" align="center"></th>
<td width="20%" align="right"> <a accesskey="n" href="data-types.html">Next</a></td>
</tr>
</table>
<hr>
</div>
<div class="chapter">
<div class="titlepage">
<div>
<div>
<h1 class="title"><a name="charset"></a>Chapter 10 Character Sets, Collations, Unicode</h1>

</div>

</div>

</div>
<div class="toc">
<p><b>Table of Contents</b></p><dl class="toc"><dt><span class="section"><a href="charset.html#charset-general">10.1 Character Sets and Collations in General</a></span></dt><dt><span class="section"><a href="charset.html#charset-mysql">10.2 Character Sets and Collations in MySQL</a></span></dt><dd><dl><dt><span class="section"><a href="charset.html#charset-repertoire">10.2.1 Character Set Repertoire</a></span></dt><dt><span class="section"><a href="charset.html#charset-metadata">10.2.2 UTF-8 for Metadata</a></span></dt></dl></dd><dt><span class="section"><a href="charset.html#charset-syntax">10.3 Specifying Character Sets and Collations</a></span></dt><dd><dl><dt><span class="section"><a href="charset.html#charset-collation-names">10.3.1 Collation Naming Conventions</a></span></dt><dt><span class="section"><a href="charset.html#charset-server">10.3.2 Server Character Set and Collation</a></span></dt><dt><span class="section"><a href="charset.html#charset-database">10.3.3 Database Character Set and Collation</a></span></dt><dt><span class="section"><a href="charset.html#charset-table">10.3.4 Table Character Set and Collation</a></span></dt><dt><span class="section"><a href="charset.html#charset-column">10.3.5 Column Character Set and Collation</a></span></dt><dt><span class="section"><a href="charset.html#charset-literal">10.3.6 Character String Literal Character Set and Collation</a></span></dt><dt><span class="section"><a href="charset.html#charset-national">10.3.7 The National Character Set</a></span></dt><dt><span class="section"><a href="charset.html#charset-introducer">10.3.8 Character Set Introducers</a></span></dt><dt><span class="section"><a href="charset.html#charset-examples">10.3.9 Examples of Character Set and Collation Assignment</a></span></dt><dt><span class="section"><a href="charset.html#charset-compatibility">10.3.10 Compatibility with Other DBMSs</a></span></dt></dl></dd><dt><span class="section"><a href="charset.html#charset-connection">10.4 Connection Character Sets and Collations</a></span></dt><dt><span class="section"><a href="charset.html#charset-applications">10.5 Configuring Application Character Set and Collation</a></span></dt><dt><span class="section"><a href="charset.html#charset-errors">10.6 Error Message Character Set</a></span></dt><dt><span class="section"><a href="charset.html#charset-conversion">10.7 Column Character Set Conversion</a></span></dt><dt><span class="section"><a href="charset.html#charset-collations">10.8 Collation Issues</a></span></dt><dd><dl><dt><span class="section"><a href="charset.html#charset-collate">10.8.1 Using COLLATE in SQL Statements</a></span></dt><dt><span class="section"><a href="charset.html#charset-collate-precedence">10.8.2 COLLATE Clause Precedence</a></span></dt><dt><span class="section"><a href="charset.html#charset-collation-compatibility">10.8.3 Character Set and Collation Compatibility</a></span></dt><dt><span class="section"><a href="charset.html#charset-collation-coercibility">10.8.4 Collation Coercibility in Expressions</a></span></dt><dt><span class="section"><a href="charset.html#charset-binary-collations">10.8.5 The binary Collation Compared to _bin Collations</a></span></dt><dt><span class="section"><a href="charset.html#charset-collation-effect">10.8.6 Examples of the Effect of Collation</a></span></dt><dt><span class="section"><a href="charset.html#charset-collation-information-schema">10.8.7 Using Collation in INFORMATION_SCHEMA Searches</a></span></dt></dl></dd><dt><span class="section"><a href="charset.html#charset-unicode">10.9 Unicode Support</a></span></dt><dd><dl><dt><span class="section"><a href="charset.html#charset-unicode-utf8mb4">10.9.1 The utf8mb4 Character Set (4-Byte UTF-8 Unicode Encoding)</a></span></dt><dt><span class="section"><a href="charset.html#charset-unicode-utf8mb3">10.9.2 The utf8mb3 Character Set (3-Byte UTF-8 Unicode Encoding)</a></span></dt><dt><span class="section"><a href="charset.html#charset-unicode-utf8">10.9.3 The utf8 Character Set (Alias for utf8mb3)</a></span></dt><dt><span class="section"><a href="charset.html#charset-unicode-ucs2">10.9.4 The ucs2 Character Set (UCS-2 Unicode Encoding)</a></span></dt><dt><span class="section"><a href="charset.html#charset-unicode-utf16">10.9.5 The utf16 Character Set (UTF-16 Unicode Encoding)</a></span></dt><dt><span class="section"><a href="charset.html#charset-unicode-utf16le">10.9.6 The utf16le Character Set (UTF-16LE Unicode Encoding)</a></span></dt><dt><span class="section"><a href="charset.html#charset-unicode-utf32">10.9.7 The utf32 Character Set (UTF-32 Unicode Encoding)</a></span></dt><dt><span class="section"><a href="charset.html#charset-unicode-conversion">10.9.8 Converting Between 3-Byte and 4-Byte Unicode Character Sets</a></span></dt></dl></dd><dt><span class="section"><a href="charset.html#charset-charsets">10.10 Supported Character Sets and Collations</a></span></dt><dd><dl><dt><span class="section"><a href="charset.html#charset-unicode-sets">10.10.1 Unicode Character Sets</a></span></dt><dt><span class="section"><a href="charset.html#charset-we-sets">10.10.2 West European Character Sets</a></span></dt><dt><span class="section"><a href="charset.html#charset-ce-sets">10.10.3 Central European Character Sets</a></span></dt><dt><span class="section"><a href="charset.html#charset-se-me-sets">10.10.4 South European and Middle East Character Sets</a></span></dt><dt><span class="section"><a href="charset.html#charset-baltic-sets">10.10.5 Baltic Character Sets</a></span></dt><dt><span class="section"><a href="charset.html#charset-cyrillic-sets">10.10.6 Cyrillic Character Sets</a></span></dt><dt><span class="section"><a href="charset.html#charset-asian-sets">10.10.7 Asian Character Sets</a></span></dt><dt><span class="section"><a href="charset.html#charset-binary-set">10.10.8 The Binary Character Set</a></span></dt></dl></dd><dt><span class="section"><a href="charset.html#error-message-language">10.11 Setting the Error Message Language</a></span></dt><dt><span class="section"><a href="charset.html#adding-character-set">10.12 Adding a Character Set</a></span></dt><dd><dl><dt><span class="section"><a href="charset.html#character-arrays">10.12.1 Character Definition Arrays</a></span></dt><dt><span class="section"><a href="charset.html#string-collating">10.12.2 String Collating Support for Complex Character Sets</a></span></dt><dt><span class="section"><a href="charset.html#multibyte-characters">10.12.3 Multi-Byte Character Support for Complex Character Sets</a></span></dt></dl></dd><dt><span class="section"><a href="charset.html#adding-collation">10.13 Adding a Collation to a Character Set</a></span></dt><dd><dl><dt><span class="section"><a href="charset.html#charset-collation-implementations">10.13.1 Collation Implementation Types</a></span></dt><dt><span class="section"><a href="charset.html#adding-collation-choosing-id">10.13.2 Choosing a Collation ID</a></span></dt><dt><span class="section"><a href="charset.html#adding-collation-simple-8bit">10.13.3 Adding a Simple Collation to an 8-Bit Character Set</a></span></dt><dt><span class="section"><a href="charset.html#adding-collation-unicode-uca">10.13.4 Adding a UCA Collation to a Unicode Character Set</a></span></dt></dl></dd><dt><span class="section"><a href="charset.html#charset-configuration">10.14 Character Set Configuration</a></span></dt><dt><span class="section"><a href="charset.html#locale-support">10.15 MySQL Server Locale Support</a></span></dt></dl>
</div>
<a class="indexterm" name="idm140091698310416"></a><a class="indexterm" name="idm140091698309376"></a><a class="indexterm" name="idm140091698308304"></a><a class="indexterm" name="idm140091698307232"></a><a class="indexterm" name="idm140091698306160"></a><p>
    MySQL includes character set support that enables you to store data
    using a variety of character sets and perform comparisons according
    to a variety of collations. You can specify character sets at the
    server, database, table, and column level.
  </p><p>
    This chapter discusses the following topics:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
        What are character sets and collations?
      </p></li><li class="listitem"><p>
        The multiple-level default system for character set assignment.
      </p></li><li class="listitem"><p>
        Syntax for specifying character sets and collations.
      </p></li><li class="listitem"><p>
        Affected functions and operations.
      </p></li><li class="listitem"><p>
        Unicode support.
      </p></li><li class="listitem"><p>
        The character sets and collations that are available, with
        notes.
      </p></li><li class="listitem"><p>
        Selecting the language for error messages.
      </p></li><li class="listitem"><p>
        Selecting the locale for day and month names.
</p></li></ul>
</div>
<p>
    Character set issues affect not only data storage, but also
    communication between client programs and the MySQL server. If you
    want the client program to communicate with the server using a
    character set different from the default, you'll need to indicate
    which one. For example, to use the <code class="literal">utf8</code> Unicode
    character set, issue this statement after connecting to the server:
  </p><pre data-lang="sql" class="programlisting">
SET NAMES 'utf8';
</pre><p>
    For more information about configuring character sets for
    application use and character set-related issues in client/server
    communication, see <a class="xref" href="charset.html#charset-applications" title="10.5 Configuring Application Character Set and Collation">Section 10.5, “Configuring Application Character Set and Collation”</a>, and
    <a class="xref" href="charset.html#charset-connection" title="10.4 Connection Character Sets and Collations">Section 10.4, “Connection Character Sets and Collations”</a>.
</p>
<div class="section">

<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both"><a name="charset-general"></a>10.1 Character Sets and Collations in General</h2>
</div>
</div>
</div>
<p>
      A <span class="firstterm">character set</span> is a set of
      symbols and encodings. A
      <span class="firstterm">collation</span> is a set of rules
      for comparing characters in a character set. Let's make the
      distinction clear with an example of an imaginary character set.
    </p><p>
      Suppose that we have an alphabet with four letters:
      <code class="literal">A</code>, <code class="literal">B</code>, <code class="literal">a</code>,
      <code class="literal">b</code>. We give each letter a number:
      <code class="literal">A</code> = 0, <code class="literal">B</code> = 1,
      <code class="literal">a</code> = 2, <code class="literal">b</code> = 3. The letter
      <code class="literal">A</code> is a symbol, the number 0 is the
      <span class="emphasis"><em>encoding</em></span> for <code class="literal">A</code>, and the
      combination of all four letters and their encodings is a
      <span class="emphasis"><em>character set</em></span>.
    </p><p>
      Suppose that we want to compare two string values,
      <code class="literal">A</code> and <code class="literal">B</code>. The simplest way to
      do this is to look at the encodings: 0 for <code class="literal">A</code>
      and 1 for <code class="literal">B</code>. Because 0 is less than 1, we say
      <code class="literal">A</code> is less than <code class="literal">B</code>. What we've
      just done is apply a collation to our character set. The collation
      is a set of rules (only one rule in this case): <span class="quote">“<span class="quote">compare the
      encodings.</span>”</span> We call this simplest of all possible
      collations a <span class="firstterm">binary</span>
      collation.
    </p><p>
      But what if we want to say that the lowercase and uppercase
      letters are equivalent? Then we would have at least two rules: (1)
      treat the lowercase letters <code class="literal">a</code> and
      <code class="literal">b</code> as equivalent to <code class="literal">A</code> and
      <code class="literal">B</code>; (2) then compare the encodings. We call this
      a <span class="firstterm">case-insensitive</span>
      collation. It is a little more complex than a binary collation.
    </p><p>
      In real life, most character sets have many characters: not just
      <code class="literal">A</code> and <code class="literal">B</code> but whole alphabets,
      sometimes multiple alphabets or eastern writing systems with
      thousands of characters, along with many special symbols and
      punctuation marks. Also in real life, most collations have many
      rules, not just for whether to distinguish lettercase, but also
      for whether to distinguish accents (an <span class="quote">“<span class="quote">accent</span>”</span> is a
      mark attached to a character as in German <code class="literal">Ö</code>),
      and for multiple-character mappings (such as the rule that
      <code class="literal">Ö</code> = <code class="literal">OE</code> in one of the two
      German collations).
    </p><p>
      MySQL can do these things for you:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          Store strings using a variety of character sets.
        </p></li><li class="listitem"><p>
          Compare strings using a variety of collations.
        </p></li><li class="listitem"><p>
          Mix strings with different character sets or collations in the
          same server, the same database, or even the same table.
        </p></li><li class="listitem"><p>
          Enable specification of character set and collation at any
          level.
</p></li></ul>
</div>
<p>
      To use these features effectively, you must know what character
      sets and collations are available, how to change the defaults, and
      how they affect the behavior of string operators and functions.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both"><a name="charset-mysql"></a>10.2 Character Sets and Collations in MySQL</h2>

</div>

</div>

</div>
<div class="toc">
<dl class="toc"><dt><span class="section"><a href="charset.html#charset-repertoire">10.2.1 Character Set Repertoire</a></span></dt><dt><span class="section"><a href="charset.html#charset-metadata">10.2.2 UTF-8 for Metadata</a></span></dt></dl>
</div>
<p>
      MySQL Server supports multiple character sets, including several
      Unicode character sets. To display the available character sets,
      use the <code class="literal">INFORMATION_SCHEMA</code>
      <a class="link" href="information-schema.html#character-sets-table" title="25.2 The INFORMATION_SCHEMA CHARACTER_SETS Table"><code class="literal">CHARACTER_SETS</code></a> table or the
      <a class="link" href="sql-syntax.html#show-character-set" title="13.7.6.3 SHOW CHARACTER SET Syntax"><code class="literal">SHOW CHARACTER SET</code></a> statement. A
      partial listing follows. For more complete information, see
      <a class="xref" href="charset.html#charset-charsets" title="10.10 Supported Character Sets and Collations">Section 10.10, “Supported Character Sets and Collations”</a>.
    </p><pre data-lang="sql" class="programlisting">
mysql&gt; <strong class="userinput"><code>SHOW CHARACTER SET;</code></strong>
+----------+---------------------------------+---------------------+--------+
| Charset  | Description                     | Default collation   | Maxlen |
+----------+---------------------------------+---------------------+--------+
| big5     | Big5 Traditional Chinese        | big5_chinese_ci     |      2 |
| binary   | Binary pseudo charset           | binary              |      1 |
...
| latin1   | cp1252 West European            | latin1_swedish_ci   |      1 |
...
| ucs2     | UCS-2 Unicode                   | ucs2_general_ci     |      2 |
...
| utf8     | UTF-8 Unicode                   | utf8_general_ci     |      3 |
| utf8mb4  | UTF-8 Unicode                   | utf8mb4_0900_ai_ci  |      4 |
...
</pre><p>
      By default, the <a class="link" href="sql-syntax.html#show-character-set" title="13.7.6.3 SHOW CHARACTER SET Syntax"><code class="literal">SHOW CHARACTER SET</code></a>
      statement displays all available character sets. It takes an
      optional <a class="link" href="functions.html#operator_like"><code class="literal">LIKE</code></a> or
      <code class="literal">WHERE</code> clause that indicates which character set
      names to match. The following example shows some of the Unicode
      character sets (those based on Unicode Transformation Format):
    </p><pre data-lang="sql" class="programlisting">
mysql&gt; <strong class="userinput"><code>SHOW CHARACTER SET LIKE 'utf%';</code></strong>
+---------+------------------+--------------------+--------+
| Charset | Description      | Default collation  | Maxlen |
+---------+------------------+--------------------+--------+
| utf16   | UTF-16 Unicode   | utf16_general_ci   |      4 |
| utf16le | UTF-16LE Unicode | utf16le_general_ci |      4 |
| utf32   | UTF-32 Unicode   | utf32_general_ci   |      4 |
| utf8    | UTF-8 Unicode    | utf8_general_ci    |      3 |
| utf8mb4 | UTF-8 Unicode    | utf8mb4_0900_ai_ci |      4 |
+---------+------------------+--------------------+--------+
</pre><p>
      A given character set always has at least one collation, and most
      character sets have several. To list the display collations for a
      character set, use the <code class="literal">INFORMATION_SCHEMA</code>
      <a class="link" href="information-schema.html#collations-table" title="25.4 The INFORMATION_SCHEMA COLLATIONS Table"><code class="literal">COLLATIONS</code></a> table or the
      <a class="link" href="sql-syntax.html#show-collation" title="13.7.6.4 SHOW COLLATION Syntax"><code class="literal">SHOW COLLATION</code></a> statement.
    </p><p>
      By default, the <a class="link" href="sql-syntax.html#show-collation" title="13.7.6.4 SHOW COLLATION Syntax"><code class="literal">SHOW COLLATION</code></a>
      statement displays all available collations. It takes an optional
      <a class="link" href="functions.html#operator_like"><code class="literal">LIKE</code></a> or <code class="literal">WHERE</code>
      clause that indicates which collation names to display. For
      example, to see the collations for the default character set,
      <code class="literal">utf8mb4</code>, use this statement:
    </p><pre data-lang="sql" class="programlisting">
mysql&gt; <strong class="userinput"><code>SHOW COLLATION WHERE Charset = 'utf8mb4';</code></strong>
+----------------------------+---------+-----+---------+----------+---------+---------------+
| Collation                  | Charset | Id  | Default | Compiled | Sortlen | Pad_attribute |
+----------------------------+---------+-----+---------+----------+---------+---------------+
| utf8mb4_0900_ai_ci         | utf8mb4 | 255 | Yes     | Yes      |       0 | NO PAD        |
| utf8mb4_0900_as_ci         | utf8mb4 | 305 |         | Yes      |       0 | NO PAD        |
| utf8mb4_0900_as_cs         | utf8mb4 | 278 |         | Yes      |       0 | NO PAD        |
| utf8mb4_0900_bin           | utf8mb4 | 309 |         | Yes      |       1 | NO PAD        |
| utf8mb4_bin                | utf8mb4 |  46 |         | Yes      |       1 | PAD SPACE     |
| utf8mb4_croatian_ci        | utf8mb4 | 245 |         | Yes      |       8 | PAD SPACE     |
| utf8mb4_cs_0900_ai_ci      | utf8mb4 | 266 |         | Yes      |       0 | NO PAD        |
| utf8mb4_cs_0900_as_cs      | utf8mb4 | 289 |         | Yes      |       0 | NO PAD        |
| utf8mb4_czech_ci           | utf8mb4 | 234 |         | Yes      |       8 | PAD SPACE     |
| utf8mb4_danish_ci          | utf8mb4 | 235 |         | Yes      |       8 | PAD SPACE     |
| utf8mb4_da_0900_ai_ci      | utf8mb4 | 267 |         | Yes      |       0 | NO PAD        |
| utf8mb4_da_0900_as_cs      | utf8mb4 | 290 |         | Yes      |       0 | NO PAD        |
| utf8mb4_de_pb_0900_ai_ci   | utf8mb4 | 256 |         | Yes      |       0 | NO PAD        |
| utf8mb4_de_pb_0900_as_cs   | utf8mb4 | 279 |         | Yes      |       0 | NO PAD        |
| utf8mb4_eo_0900_ai_ci      | utf8mb4 | 273 |         | Yes      |       0 | NO PAD        |
| utf8mb4_eo_0900_as_cs      | utf8mb4 | 296 |         | Yes      |       0 | NO PAD        |
| utf8mb4_esperanto_ci       | utf8mb4 | 241 |         | Yes      |       8 | PAD SPACE     |
| utf8mb4_estonian_ci        | utf8mb4 | 230 |         | Yes      |       8 | PAD SPACE     |
| utf8mb4_es_0900_ai_ci      | utf8mb4 | 263 |         | Yes      |       0 | NO PAD        |
| utf8mb4_es_0900_as_cs      | utf8mb4 | 286 |         | Yes      |       0 | NO PAD        |
| utf8mb4_es_trad_0900_ai_ci | utf8mb4 | 270 |         | Yes      |       0 | NO PAD        |
| utf8mb4_es_trad_0900_as_cs | utf8mb4 | 293 |         | Yes      |       0 | NO PAD        |
| utf8mb4_et_0900_ai_ci      | utf8mb4 | 262 |         | Yes      |       0 | NO PAD        |
| utf8mb4_et_0900_as_cs      | utf8mb4 | 285 |         | Yes      |       0 | NO PAD        |
| utf8mb4_general_ci         | utf8mb4 |  45 |         | Yes      |       1 | PAD SPACE     |
| utf8mb4_german2_ci         | utf8mb4 | 244 |         | Yes      |       8 | PAD SPACE     |
| utf8mb4_hr_0900_ai_ci      | utf8mb4 | 275 |         | Yes      |       0 | NO PAD        |
| utf8mb4_hr_0900_as_cs      | utf8mb4 | 298 |         | Yes      |       0 | NO PAD        |
| utf8mb4_hungarian_ci       | utf8mb4 | 242 |         | Yes      |       8 | PAD SPACE     |
| utf8mb4_hu_0900_ai_ci      | utf8mb4 | 274 |         | Yes      |       0 | NO PAD        |
| utf8mb4_hu_0900_as_cs      | utf8mb4 | 297 |         | Yes      |       0 | NO PAD        |
| utf8mb4_icelandic_ci       | utf8mb4 | 225 |         | Yes      |       8 | PAD SPACE     |
| utf8mb4_is_0900_ai_ci      | utf8mb4 | 257 |         | Yes      |       0 | NO PAD        |
| utf8mb4_is_0900_as_cs      | utf8mb4 | 280 |         | Yes      |       0 | NO PAD        |
| utf8mb4_ja_0900_as_cs      | utf8mb4 | 303 |         | Yes      |       0 | NO PAD        |
| utf8mb4_ja_0900_as_cs_ks   | utf8mb4 | 304 |         | Yes      |      24 | NO PAD        |
| utf8mb4_latvian_ci         | utf8mb4 | 226 |         | Yes      |       8 | PAD SPACE     |
| utf8mb4_la_0900_ai_ci      | utf8mb4 | 271 |         | Yes      |       0 | NO PAD        |
| utf8mb4_la_0900_as_cs      | utf8mb4 | 294 |         | Yes      |       0 | NO PAD        |
| utf8mb4_lithuanian_ci      | utf8mb4 | 236 |         | Yes      |       8 | PAD SPACE     |
| utf8mb4_lt_0900_ai_ci      | utf8mb4 | 268 |         | Yes      |       0 | NO PAD        |
| utf8mb4_lt_0900_as_cs      | utf8mb4 | 291 |         | Yes      |       0 | NO PAD        |
| utf8mb4_lv_0900_ai_ci      | utf8mb4 | 258 |         | Yes      |       0 | NO PAD        |
| utf8mb4_lv_0900_as_cs      | utf8mb4 | 281 |         | Yes      |       0 | NO PAD        |
| utf8mb4_persian_ci         | utf8mb4 | 240 |         | Yes      |       8 | PAD SPACE     |
| utf8mb4_pl_0900_ai_ci      | utf8mb4 | 261 |         | Yes      |       0 | NO PAD        |
| utf8mb4_pl_0900_as_cs      | utf8mb4 | 284 |         | Yes      |       0 | NO PAD        |
| utf8mb4_polish_ci          | utf8mb4 | 229 |         | Yes      |       8 | PAD SPACE     |
| utf8mb4_romanian_ci        | utf8mb4 | 227 |         | Yes      |       8 | PAD SPACE     |
| utf8mb4_roman_ci           | utf8mb4 | 239 |         | Yes      |       8 | PAD SPACE     |
| utf8mb4_ro_0900_ai_ci      | utf8mb4 | 259 |         | Yes      |       0 | NO PAD        |
| utf8mb4_ro_0900_as_cs      | utf8mb4 | 282 |         | Yes      |       0 | NO PAD        |
| utf8mb4_ru_0900_ai_ci      | utf8mb4 | 306 |         | Yes      |       0 | NO PAD        |
| utf8mb4_ru_0900_as_cs      | utf8mb4 | 307 |         | Yes      |       0 | NO PAD        |
| utf8mb4_sinhala_ci         | utf8mb4 | 243 |         | Yes      |       8 | PAD SPACE     |
| utf8mb4_sk_0900_ai_ci      | utf8mb4 | 269 |         | Yes      |       0 | NO PAD        |
| utf8mb4_sk_0900_as_cs      | utf8mb4 | 292 |         | Yes      |       0 | NO PAD        |
| utf8mb4_slovak_ci          | utf8mb4 | 237 |         | Yes      |       8 | PAD SPACE     |
| utf8mb4_slovenian_ci       | utf8mb4 | 228 |         | Yes      |       8 | PAD SPACE     |
| utf8mb4_sl_0900_ai_ci      | utf8mb4 | 260 |         | Yes      |       0 | NO PAD        |
| utf8mb4_sl_0900_as_cs      | utf8mb4 | 283 |         | Yes      |       0 | NO PAD        |
| utf8mb4_spanish2_ci        | utf8mb4 | 238 |         | Yes      |       8 | PAD SPACE     |
| utf8mb4_spanish_ci         | utf8mb4 | 231 |         | Yes      |       8 | PAD SPACE     |
| utf8mb4_sv_0900_ai_ci      | utf8mb4 | 264 |         | Yes      |       0 | NO PAD        |
| utf8mb4_sv_0900_as_cs      | utf8mb4 | 287 |         | Yes      |       0 | NO PAD        |
| utf8mb4_swedish_ci         | utf8mb4 | 232 |         | Yes      |       8 | PAD SPACE     |
| utf8mb4_tr_0900_ai_ci      | utf8mb4 | 265 |         | Yes      |       0 | NO PAD        |
| utf8mb4_tr_0900_as_cs      | utf8mb4 | 288 |         | Yes      |       0 | NO PAD        |
| utf8mb4_turkish_ci         | utf8mb4 | 233 |         | Yes      |       8 | PAD SPACE     |
| utf8mb4_unicode_520_ci     | utf8mb4 | 246 |         | Yes      |       8 | PAD SPACE     |
| utf8mb4_unicode_ci         | utf8mb4 | 224 |         | Yes      |       8 | PAD SPACE     |
| utf8mb4_vietnamese_ci      | utf8mb4 | 247 |         | Yes      |       8 | PAD SPACE     |
| utf8mb4_vi_0900_ai_ci      | utf8mb4 | 277 |         | Yes      |       0 | NO PAD        |
| utf8mb4_vi_0900_as_cs      | utf8mb4 | 300 |         | Yes      |       0 | NO PAD        |
| utf8mb4_zh_0900_as_cs      | utf8mb4 | 308 |         | Yes      |       0 | NO PAD        |
+----------------------------+---------+-----+---------+----------+---------+---------------+
</pre><p>
      For more information about those collations, see
      <a class="xref" href="charset.html#charset-unicode-sets" title="10.10.1 Unicode Character Sets">Section 10.10.1, “Unicode Character Sets”</a>.
    </p><p>
      Collations have these general characteristics:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          Two different character sets cannot have the same collation.
        </p></li><li class="listitem"><p>
          Each character set has a <span class="emphasis"><em>default
          collation</em></span>. For example, the default collations for
          <code class="literal">utf8mb4</code> and <code class="literal">latin1</code> are
          <code class="literal">utf8mb4_0900_ai_ci</code> and
          <code class="literal">latin1_swedish_ci</code>, respectively. The
          <code class="literal">INFORMATION_SCHEMA</code>
          <a class="link" href="information-schema.html#character-sets-table" title="25.2 The INFORMATION_SCHEMA CHARACTER_SETS Table"><code class="literal">CHARACTER_SETS</code></a> table and the
          <a class="link" href="sql-syntax.html#show-character-set" title="13.7.6.3 SHOW CHARACTER SET Syntax"><code class="literal">SHOW CHARACTER SET</code></a> statement
          indicate the default collation for each character set. The
          <code class="literal">INFORMATION_SCHEMA</code>
          <a class="link" href="information-schema.html#collations-table" title="25.4 The INFORMATION_SCHEMA COLLATIONS Table"><code class="literal">COLLATIONS</code></a> table and the
          <a class="link" href="sql-syntax.html#show-collation" title="13.7.6.4 SHOW COLLATION Syntax"><code class="literal">SHOW COLLATION</code></a> statement have a
          column that indicates for each collation whether it is the
          default for its character set (<code class="literal">Yes</code> if so,
          empty if not).
        </p></li><li class="listitem"><p>
          Collation names start with the name of the character set with
          which they are associated, generally followed by one or more
          suffixes indicating other collation characteristics. For
          additional information about naming conventions, see
          <a class="xref" href="charset.html#charset-collation-names" title="10.3.1 Collation Naming Conventions">Section 10.3.1, “Collation Naming Conventions”</a>.
</p></li></ul>
</div>
<p>
      When a character set has multiple collations, it might not be
      clear which collation is most suitable for a given application. To
      avoid choosing an inappropriate collation, perform some
      comparisons with representative data values to make sure that a
      given collation sorts values the way you expect.
</p>
<div class="section">

<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="charset-repertoire"></a>10.2.1 Character Set Repertoire</h3>
</div>
</div>
</div>
<a class="indexterm" name="idm140091698208144"></a><a class="indexterm" name="idm140091698206688"></a><a class="indexterm" name="idm140091698205200"></a><a class="indexterm" name="idm140091698203712"></a><p>
        The <span class="firstterm">repertoire</span> of a
        character set is the collection of characters in the set.
      </p><p>
        String expressions have a repertoire attribute, which can have
        two values:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            <code class="literal">ASCII</code>: The expression can contain only
            characters in the Unicode range <code class="literal">U+0000</code> to
            <code class="literal">U+007F</code>.
          </p></li><li class="listitem"><p>
            <code class="literal">UNICODE</code>: The expression can contain
            characters in the Unicode range <code class="literal">U+0000</code> to
            <code class="literal">U+10FFFF</code>. This includes characters in the
            Basic Multilingual Plane (BMP) range
            (<code class="literal">U+0000</code> to <code class="literal">U+FFFF</code>) and
            supplementary characters outside the BMP range
            (<code class="literal">U+10000</code> to <code class="literal">U+10FFFF</code>).
</p></li></ul>
</div>
<p>
        The <code class="literal">ASCII</code> range is a subset of
        <code class="literal">UNICODE</code> range, so a string with
        <code class="literal">ASCII</code> repertoire can be converted safely
        without loss of information to the character set of any string
        with <code class="literal">UNICODE</code> repertoire or to a character set
        that is a superset of <code class="literal">ASCII</code>. (All MySQL
        character sets are supersets of <code class="literal">ASCII</code> with
        the exception of <code class="literal">swe7</code>, which reuses some
        punctuation characters for Swedish accented characters.) The use
        of repertoire enables character set conversion in expressions
        for many cases where MySQL would otherwise return an
        <span class="quote">“<span class="quote">illegal mix of collations</span>”</span> error.
      </p><p>
        The following discussion provides examples of expressions and
        their repertoires, and describes how the use of repertoire
        changes string expression evaluation:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            The repertoire for a string constant depends on string
            content and may differ from the repertoire of the string
            character set. Consider these statements:
          </p><pre data-lang="sql" class="programlisting">
SET NAMES utf8; SELECT 'abc';
SELECT _utf8'def';
SELECT N'MySQL';
</pre><p>
            Although the character set is <code class="literal">utf8</code> in
            each of the preceding cases, the strings do not actually
            contain any characters outside the ASCII range, so their
            repertoire is <code class="literal">ASCII</code> rather than
            <code class="literal">UNICODE</code>.
          </p></li><li class="listitem"><p>
            A column having the <code class="literal">ascii</code> character set
            has <code class="literal">ASCII</code> repertoire because of its
            character set. In the following table, <code class="literal">c1</code>
            has <code class="literal">ASCII</code> repertoire:
          </p><pre data-lang="sql" class="programlisting">
CREATE TABLE t1 (c1 CHAR(1) CHARACTER SET ascii);
</pre><p>
            The following example illustrates how repertoire enables a
            result to be determined in a case where an error occurs
            without repertoire:
          </p><pre data-lang="sql" class="programlisting">
CREATE TABLE t1 (
  c1 CHAR(1) CHARACTER SET latin1,
  c2 CHAR(1) CHARACTER SET ascii
);
INSERT INTO t1 VALUES ('a','b');
SELECT CONCAT(c1,c2) FROM t1;
</pre><p>
            Without repertoire, this error occurs:
          </p><pre data-lang="none" class="programlisting">
ERROR 1267 (HY000): Illegal mix of collations (latin1_swedish_ci,IMPLICIT)
and (ascii_general_ci,IMPLICIT) for operation 'concat'
</pre><p>
            Using repertoire, subset to superset
            (<code class="literal">ascii</code> to <code class="literal">latin1</code>)
            conversion can occur and a result is returned:
          </p><pre data-lang="simple" class="programlisting">
+---------------+
| CONCAT(c1,c2) |
+---------------+
| ab            |
+---------------+
</pre></li><li class="listitem"><p>
            Functions with one string argument inherit the repertoire of
            their argument. The result of
            <a class="link" href="functions.html#function_upper"><code class="literal">UPPER(_utf8'<em class="replaceable"><code>abc</code></em>')</code></a>
            has <code class="literal">ASCII</code> repertoire because its argument
            has <code class="literal">ASCII</code> repertoire.
          </p></li><li class="listitem"><p>
            For functions that return a string but do not have string
            arguments and use
            <a class="link" href="server-administration.html#sysvar_character_set_connection"><code class="literal">character_set_connection</code></a> as
            the result character set, the result repertoire is
            <code class="literal">ASCII</code> if
            <a class="link" href="server-administration.html#sysvar_character_set_connection"><code class="literal">character_set_connection</code></a> is
            <code class="literal">ascii</code>, and <code class="literal">UNICODE</code>
            otherwise:
          </p><pre data-lang="sql" class="programlisting">
FORMAT(<em class="replaceable"><code>numeric_column</code></em>, 4);
</pre><p>
            Use of repertoire changes how MySQL evaluates the following
            example:
          </p><pre data-lang="sql" class="programlisting">
SET NAMES ascii;
CREATE TABLE t1 (a INT, b VARCHAR(10) CHARACTER SET latin1);
INSERT INTO t1 VALUES (1,'b');
SELECT CONCAT(FORMAT(a, 4), b) FROM t1;
</pre><p>
            Without repertoire, this error occurs:
          </p><pre data-lang="none" class="programlisting">
ERROR 1267 (HY000): Illegal mix of collations (ascii_general_ci,COERCIBLE)
and (latin1_swedish_ci,IMPLICIT) for operation 'concat'
</pre><p>
            With repertoire, a result is returned:
          </p><pre data-lang="sql" class="programlisting">
+-------------------------+
| CONCAT(FORMAT(a, 4), b) |
+-------------------------+
| 1.0000b                 |
+-------------------------+
</pre></li><li class="listitem"><p>
            Functions with two or more string arguments use the
            <span class="quote">“<span class="quote">widest</span>”</span> argument repertoire for the result
            repertoire (<code class="literal">UNICODE</code> is wider than
            <code class="literal">ASCII</code>). Consider the following
            <a class="link" href="functions.html#function_concat"><code class="literal">CONCAT()</code></a> calls:
          </p><pre data-lang="sql" class="programlisting">
CONCAT(_ucs2 X'0041', _ucs2 X'0042')
CONCAT(_ucs2 X'0041', _ucs2 X'00C2')
</pre><p>
            For the first call, the repertoire is
            <code class="literal">ASCII</code> because both arguments are within
            the range of the <code class="literal">ascii</code> character set. For
            the second call, the repertoire is
            <code class="literal">UNICODE</code> because the second argument is
            outside the <code class="literal">ascii</code> character set range.
          </p></li><li class="listitem"><p>
            The repertoire for function return values is determined
            based only on the repertoire of the arguments that affect
            the result's character set and collation.
          </p><pre data-lang="sql" class="programlisting">
IF(column1 &lt; column2, 'smaller', 'greater')
</pre><p>
            The result repertoire is <code class="literal">ASCII</code> because
            the two string arguments (the second argument and the third
            argument) both have <code class="literal">ASCII</code> repertoire. The
            first argument does not matter for the result repertoire,
            even if the expression uses string values.
</p></li></ul>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="charset-metadata"></a>10.2.2 UTF-8 for Metadata</h3>

</div>

</div>

</div>
<a class="indexterm" name="idm140091698138240"></a><a class="indexterm" name="idm140091698136752"></a><a class="indexterm" name="idm140091698135264"></a><p>
        <span class="firstterm">Metadata</span> is <span class="quote">“<span class="quote">the
        data about the data.</span>”</span> Anything that
        <span class="emphasis"><em>describes</em></span> the database—as opposed to
        being the <span class="emphasis"><em>contents</em></span> of the database—is
        metadata. Thus column names, database names, user names, version
        names, and most of the string results from
        <a class="link" href="sql-syntax.html#show" title="13.7.6 SHOW Syntax"><code class="literal">SHOW</code></a> are metadata. This is also
        true of the contents of tables in
        <code class="literal">INFORMATION_SCHEMA</code> because those tables by
        definition contain information about database objects.
      </p><p>
        Representation of metadata must satisfy these requirements:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            All metadata must be in the same character set. Otherwise,
            neither the <a class="link" href="sql-syntax.html#show" title="13.7.6 SHOW Syntax"><code class="literal">SHOW</code></a> statements
            nor <a class="link" href="sql-syntax.html#select" title="13.2.10 SELECT Syntax"><code class="literal">SELECT</code></a> statements for
            tables in <code class="literal">INFORMATION_SCHEMA</code> would work
            properly because different rows in the same column of the
            results of these operations would be in different character
            sets.
          </p></li><li class="listitem"><p>
            Metadata must include all characters in all languages.
            Otherwise, users would not be able to name columns and
            tables using their own languages.
</p></li></ul>
</div>
<p>
        To satisfy both requirements, MySQL stores metadata in a Unicode
        character set, namely UTF-8. This does not cause any disruption
        if you never use accented or non-Latin characters. But if you
        do, you should be aware that metadata is in UTF-8.
      </p><p>
        The metadata requirements mean that the return values of the
        <a class="link" href="functions.html#function_user"><code class="literal">USER()</code></a>,
        <a class="link" href="functions.html#function_current-user"><code class="literal">CURRENT_USER()</code></a>,
        <a class="link" href="functions.html#function_session-user"><code class="literal">SESSION_USER()</code></a>,
        <a class="link" href="functions.html#function_system-user"><code class="literal">SYSTEM_USER()</code></a>,
        <a class="link" href="functions.html#function_database"><code class="literal">DATABASE()</code></a>, and
        <a class="link" href="functions.html#function_version"><code class="literal">VERSION()</code></a> functions have the
        UTF-8 character set by default.
      </p><p>
        The server sets the
        <a class="link" href="server-administration.html#sysvar_character_set_system"><code class="literal">character_set_system</code></a> system
        variable to the name of the metadata character set:
      </p><pre data-lang="sql" class="programlisting">
mysql&gt; <strong class="userinput"><code>SHOW VARIABLES LIKE 'character_set_system';</code></strong>
+----------------------+-------+
| Variable_name        | Value |
+----------------------+-------+
| character_set_system | utf8  |
+----------------------+-------+
</pre><p>
        Storage of metadata using Unicode does <span class="emphasis"><em>not</em></span>
        mean that the server returns headers of columns and the results
        of <a class="link" href="sql-syntax.html#describe" title="13.8.1 DESCRIBE Syntax"><code class="literal">DESCRIBE</code></a> functions in the
        <a class="link" href="server-administration.html#sysvar_character_set_system"><code class="literal">character_set_system</code></a> character
        set by default. When you use <code class="literal">SELECT column1 FROM
        t</code>, the name <code class="literal">column1</code> itself is
        returned from the server to the client in the character set
        determined by the value of the
        <a class="link" href="server-administration.html#sysvar_character_set_results"><code class="literal">character_set_results</code></a> system
        variable, which has a default value of
        <code class="literal">utf8mb4</code>. If you want the server to pass
        metadata results back in a different character set, use the
        <a class="link" href="sql-syntax.html#set-names" title="13.7.5.3 SET NAMES Syntax"><code class="literal">SET NAMES</code></a> statement to force the
        server to perform character set conversion.
        <a class="link" href="sql-syntax.html#set-names" title="13.7.5.3 SET NAMES Syntax"><code class="literal">SET NAMES</code></a> sets the
        <a class="link" href="server-administration.html#sysvar_character_set_results"><code class="literal">character_set_results</code></a> and other
        related system variables. (See
        <a class="xref" href="charset.html#charset-connection" title="10.4 Connection Character Sets and Collations">Section 10.4, “Connection Character Sets and Collations”</a>.) Alternatively, a client
        program can perform the conversion after receiving the result
        from the server. It is more efficient for the client to perform
        the conversion, but this option is not always available for all
        clients.
      </p><p>
        If <a class="link" href="server-administration.html#sysvar_character_set_results"><code class="literal">character_set_results</code></a> is set
        to <code class="literal">NULL</code>, no conversion is performed and the
        server returns metadata using its original character set (the
        set indicated by
        <a class="link" href="server-administration.html#sysvar_character_set_system"><code class="literal">character_set_system</code></a>).
      </p><p>
        Error messages returned from the server to the client are
        converted to the client character set automatically, as with
        metadata.
      </p><p>
        If you are using (for example) the
        <a class="link" href="functions.html#function_user"><code class="literal">USER()</code></a> function for comparison or
        assignment within a single statement, don't worry. MySQL
        performs some automatic conversion for you.
      </p><pre data-lang="sql" class="programlisting">
SELECT * FROM t1 WHERE USER() = latin1_column;
</pre><p>
        This works because the contents of
        <code class="literal">latin1_column</code> are automatically converted to
        UTF-8 before the comparison.
      </p><pre data-lang="sql" class="programlisting">
INSERT INTO t1 (latin1_column) SELECT USER();
</pre><p>
        This works because the contents of
        <a class="link" href="functions.html#function_user"><code class="literal">USER()</code></a> are automatically
        converted to <code class="literal">latin1</code> before the assignment.
      </p><p>
        Although automatic conversion is not in the SQL standard, the
        standard does say that every character set is (in terms of
        supported characters) a <span class="quote">“<span class="quote">subset</span>”</span> of Unicode.
        Because it is a well-known principle that <span class="quote">“<span class="quote">what applies to
        a superset can apply to a subset,</span>”</span> we believe that a
        collation for Unicode can apply for comparisons with non-Unicode
        strings. For more information about coercion of strings, see
        <a class="xref" href="charset.html#charset-collation-coercibility" title="10.8.4 Collation Coercibility in Expressions">Section 10.8.4, “Collation Coercibility in Expressions”</a>.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both"><a name="charset-syntax"></a>10.3 Specifying Character Sets and Collations</h2>

</div>

</div>

</div>
<div class="toc">
<dl class="toc"><dt><span class="section"><a href="charset.html#charset-collation-names">10.3.1 Collation Naming Conventions</a></span></dt><dt><span class="section"><a href="charset.html#charset-server">10.3.2 Server Character Set and Collation</a></span></dt><dt><span class="section"><a href="charset.html#charset-database">10.3.3 Database Character Set and Collation</a></span></dt><dt><span class="section"><a href="charset.html#charset-table">10.3.4 Table Character Set and Collation</a></span></dt><dt><span class="section"><a href="charset.html#charset-column">10.3.5 Column Character Set and Collation</a></span></dt><dt><span class="section"><a href="charset.html#charset-literal">10.3.6 Character String Literal Character Set and Collation</a></span></dt><dt><span class="section"><a href="charset.html#charset-national">10.3.7 The National Character Set</a></span></dt><dt><span class="section"><a href="charset.html#charset-introducer">10.3.8 Character Set Introducers</a></span></dt><dt><span class="section"><a href="charset.html#charset-examples">10.3.9 Examples of Character Set and Collation Assignment</a></span></dt><dt><span class="section"><a href="charset.html#charset-compatibility">10.3.10 Compatibility with Other DBMSs</a></span></dt></dl>
</div>
<p>
      There are default settings for character sets and collations at
      four levels: server, database, table, and column. The description
      in the following sections may appear complex, but it has been
      found in practice that multiple-level defaulting leads to natural
      and obvious results.
    </p><p>
      <code class="literal">CHARACTER SET</code> is used in clauses that specify a
      character set. <code class="literal">CHARSET</code> can be used as a synonym
      for <code class="literal">CHARACTER SET</code>.
    </p><p>
      Character set issues affect not only data storage, but also
      communication between client programs and the MySQL server. If you
      want the client program to communicate with the server using a
      character set different from the default, you'll need to indicate
      which one. For example, to use the <code class="literal">utf8mb4</code>
      Unicode character set, issue this statement after connecting to
      the server:
    </p><pre data-lang="sql" class="programlisting">
SET NAMES 'utf8mb4';
</pre><p>
      For more information about character set-related issues in
      client/server communication, see
      <a class="xref" href="charset.html#charset-connection" title="10.4 Connection Character Sets and Collations">Section 10.4, “Connection Character Sets and Collations”</a>.
</p>
<div class="section">

<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="charset-collation-names"></a>10.3.1 Collation Naming Conventions</h3>
</div>
</div>
</div>
<a class="indexterm" name="idm140091698074496"></a><p>
        MySQL collation names follow these conventions:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            A collation name starts with the name of the character set
            with which it is associated, generally followed by one or
            more suffixes indicating other collation characteristics.
            For example, <code class="literal">utf8mb4_general_ci</code> and
            <code class="literal">latin1_swedish_ci</code> are collations for the
            <code class="literal">utf8mb4</code> and <code class="literal">latin1</code>
            character sets, respectively. The <code class="literal">binary</code>
            character set has a single collation, also named
            <code class="literal">binary</code>, with no suffixes.
          </p></li><li class="listitem"><p>
            A language-specific collation includes a locale code or
            language name. For example,
            <code class="literal">utf8mb4_tr_0900_ai_ci</code> and
            <code class="literal">utf8mb4_hu_0900_ai_ci</code> sort characters for
            the <code class="literal">utf8mb4</code> character set using the rules
            of Turkish and Hungarian, respectively.
            <code class="literal">utf8mb4_turkish_ci</code> and
            <code class="literal">utf8mb4_hungarian_ci</code> are similar but
            based on a less recent version of the Unicode Collation
            Algorithm.
          </p></li><li class="listitem"><p>
            Collation suffixes indicate whether a collation is case and
            accent sensitive, or binary. The following table shows the
            suffixes used to indicate these characteristics.
</p><a class="indexterm" name="idm140091698061280"></a><a class="indexterm" name="idm140091698060208"></a><a class="indexterm" name="idm140091698058720"></a><a class="indexterm" name="idm140091698057648"></a><a class="indexterm" name="idm140091698056160"></a><a class="indexterm" name="idm140091698055088"></a><a class="indexterm" name="idm140091698053600"></a><a class="indexterm" name="idm140091698052528"></a><a class="indexterm" name="idm140091698051040"></a><a class="indexterm" name="idm140091698049968"></a><a class="indexterm" name="idm140091698048480"></a><a class="indexterm" name="idm140091698047408"></a>
<div class="table">
<a name="charset-collation-sensitivity-suffixes"></a><p class="title"><b>Table 10.1 Collation Case/Accent Sensitivity Suffixes</b></p>
<div class="table-contents">
<table summary="Collation suffixes that indicate case and accent sensitivity."><col width="20%"><col width="80%"><thead><tr>
                <th scope="col">Suffix</th>
                <th scope="col">Meaning</th>
              </tr></thead><tbody><tr>
                <td scope="row"><code class="literal">_ai</code></td>
                <td>Accent insensitive</td>
              </tr><tr>
                <td scope="row"><code class="literal">_as</code></td>
                <td>Accent sensitive</td>
              </tr><tr>
                <td scope="row"><code class="literal">_ci</code></td>
                <td>Case insensitive</td>
              </tr><tr>
                <td scope="row"><code class="literal">_cs</code></td>
                <td>case-sensitive</td>
              </tr><tr>
                <td scope="row"><code class="literal">_ks</code></td>
                <td>Kana sensitive</td>
              </tr><tr>
                <td scope="row"><code class="literal">_bin</code></td>
                <td>Binary</td>
</tr></tbody></table>
</div>

</div>
<br class="table-break"><p>
            For nonbinary collation names that do not specify accent
            sensitivity, it is determined by case sensitivity. If a
            collation name does not contain <code class="literal">_ai</code> or
            <code class="literal">_as</code>, <code class="literal">_ci</code> in the name
            implies <code class="literal">_ai</code> and <code class="literal">_cs</code> in
            the name implies <code class="literal">_as</code>. For example,
            <code class="literal">latin1_general_ci</code> is explicitly case
            insensitive and implicitly accent insensitive,
            <code class="literal">latin1_general_cs</code> is explicitly case
            sensitive and implicitly accent sensitive, and
            <code class="literal">utf8mb4_0900_ai_ci</code> is explicitly case and
            accent insensitive.
          </p><p>
            For Japanese collations, the <code class="literal">_ks</code> suffix
            indicates that a collation is kana sensitive; that is, it
            distinguishes Katakana characters from Hiragana characters.
            Japanese collations without the <code class="literal">_ks</code>
            suffix are not kana sensitive and treat Katakana and
            Hiragana characters equal for sorting.
          </p><p>
            For the <code class="literal">binary</code> collation of the
            <code class="literal">binary</code> character set, comparisons are
            based on numeric byte values. For the
            <code class="literal">_bin</code> collation of a nonbinary character
            set, comparisons are based on numeric character code values,
            which differ from byte values for multibyte characters. For
            more information, see
            <a class="xref" href="charset.html#charset-binary-collations" title="10.8.5 The binary Collation Compared to _bin Collations">Section 10.8.5, “The binary Collation Compared to _bin Collations”</a>.
          </p></li><li class="listitem"><p>
            For Unicode character sets, collation names may include a
            version number to indicate the version of the Unicode
            Collation Algorithm (UCA) on which the collation is based.
            UCA-based collations without a version number in the name
            use the version-4.0.0 UCA weight keys. For example:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
                <code class="literal">utf8mb4_0900_ai_ci</code> is based on UCA
                9.0.0 weight keys
                (<a class="ulink" href="http://www.unicode.org/Public/UCA/9.0.0/allkeys.txt" target="_top">http://www.unicode.org/Public/UCA/9.0.0/allkeys.txt</a>).
              </p></li><li class="listitem"><p>
                <code class="literal">utf8mb4_unicode_520_ci</code> is based on
                UCA 5.2.0 weight keys
                (<a class="ulink" href="http://www.unicode.org/Public/UCA/5.2.0/allkeys.txt" target="_top">http://www.unicode.org/Public/UCA/5.2.0/allkeys.txt</a>).
              </p></li><li class="listitem"><p>
                <code class="literal">utf8mb4_unicode_ci</code> (with no version
                named) is based on UCA 4.0.0 weight keys
                (<a class="ulink" href="http://www.unicode.org/Public/UCA/4.0.0/allkeys-4.0.0.txt" target="_top">http://www.unicode.org/Public/UCA/4.0.0/allkeys-4.0.0.txt</a>).
</p></li></ul>
</div>
</li><li class="listitem"><p>
            For Unicode character sets, the
            <code class="literal"><em class="replaceable"><code>xxx</code></em>_general_mysql500_ci</code>
            collations preserve the pre-5.1.24 ordering of the original
            <code class="literal"><em class="replaceable"><code>xxx</code></em>_general_ci</code>
            collations and permit upgrades for tables created before
            MySQL 5.1.24 (Bug #27877).
</p></li></ul>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="charset-server"></a>10.3.2 Server Character Set and Collation</h3>

</div>

</div>

</div>
<p>
        MySQL Server has a server character set and a server collation.
        These can be set at server startup on the command line or in an
        option file and changed at runtime.
      </p><p>
        Initially, the server character set and collation depend on the
        options that you use when you start <a class="link" href="programs.html#mysqld" title="4.3.1 mysqld — The MySQL Server"><span class="command"><strong>mysqld</strong></span></a>.
        You can use
        <a class="link" href="server-administration.html#sysvar_character_set_server"><code class="option">--character-set-server</code></a> for the
        character set. Along with it, you can add
        <a class="link" href="server-administration.html#sysvar_collation_server"><code class="option">--collation-server</code></a> for the
        collation. If you don't specify a character set, that is the
        same as saying
        <a class="link" href="server-administration.html#sysvar_character_set_server"><code class="option">--character-set-server=utf8mb4</code></a>.
        If you specify only a character set (for example,
        <code class="literal">utf8mb4</code>) but not a collation, that is the
        same as saying
        <a class="link" href="server-administration.html#sysvar_character_set_server"><code class="option">--character-set-server=utf8mb4</code></a>
        <a class="link" href="server-administration.html#sysvar_collation_server"><code class="option">--collation-server=utf8mb4_0900_ai_ci</code></a>
        because <code class="literal">utf8mb4_0900_ai_ci</code> is the default
        collation for <code class="literal">utf8mb4</code>. Therefore, the
        following three commands all have the same effect:
      </p><pre data-lang="terminal" class="programlisting">
mysqld
mysqld --character-set-server=utf8mb4
mysqld --character-set-server=utf8mb4 \
  --collation-server=utf8mb4_0900_ai_ci
</pre><p>
        One way to change the settings is by recompiling. To change the
        default server character set and collation when building from
        sources, use the <a class="link" href="installing.html#option_cmake_default_charset"><code class="option">DEFAULT_CHARSET</code></a>
        and <a class="link" href="installing.html#option_cmake_default_collation"><code class="option">DEFAULT_COLLATION</code></a> options for
        <span class="command"><strong>CMake</strong></span>. For example:
      </p><pre data-lang="terminal" class="programlisting">
cmake . -DDEFAULT_CHARSET=latin1
</pre><p>
        Or:
      </p><pre data-lang="terminal" class="programlisting">
cmake . -DDEFAULT_CHARSET=latin1 \
  -DDEFAULT_COLLATION=latin1_german1_ci
</pre><p>
        Both <a class="link" href="programs.html#mysqld" title="4.3.1 mysqld — The MySQL Server"><span class="command"><strong>mysqld</strong></span></a> and <span class="command"><strong>CMake</strong></span>
        verify that the character set/collation combination is valid. If
        not, each program displays an error message and terminates.
      </p><p>
        The server character set and collation are used as default
        values if the database character set and collation are not
        specified in <a class="link" href="sql-syntax.html#create-database" title="13.1.12 CREATE DATABASE Syntax"><code class="literal">CREATE DATABASE</code></a>
        statements. They have no other purpose.
      </p><p>
        The current server character set and collation can be determined
        from the values of the
        <a class="link" href="server-administration.html#sysvar_character_set_server"><code class="literal">character_set_server</code></a> and
        <a class="link" href="server-administration.html#sysvar_collation_server"><code class="literal">collation_server</code></a> system
        variables. These variables can be changed at runtime.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="charset-database"></a>10.3.3 Database Character Set and Collation</h3>

</div>

</div>

</div>
<p>
        Every database has a database character set and a database
        collation. The <a class="link" href="sql-syntax.html#create-database" title="13.1.12 CREATE DATABASE Syntax"><code class="literal">CREATE DATABASE</code></a>
        and <a class="link" href="sql-syntax.html#alter-database" title="13.1.2 ALTER DATABASE Syntax"><code class="literal">ALTER DATABASE</code></a> statements
        have optional clauses for specifying the database character set
        and collation:
      </p><pre data-lang="sql" class="programlisting">
CREATE DATABASE <em class="replaceable"><code>db_name</code></em>
    [[DEFAULT] CHARACTER SET <em class="replaceable"><code>charset_name</code></em>]
    [[DEFAULT] COLLATE <em class="replaceable"><code>collation_name</code></em>]

ALTER DATABASE <em class="replaceable"><code>db_name</code></em>
    [[DEFAULT] CHARACTER SET <em class="replaceable"><code>charset_name</code></em>]
    [[DEFAULT] COLLATE <em class="replaceable"><code>collation_name</code></em>]
</pre><p>
        The keyword <code class="literal">SCHEMA</code> can be used instead of
        <code class="literal">DATABASE</code>.
      </p><p>
        The <code class="literal">CHARACTER SET</code> and
        <code class="literal">COLLATE</code> clauses make it possible to create
        databases with different character sets and collations on the
        same MySQL server.
      </p><p>
        Database options are stored in the data dictionary and can be
        examined by checking the
        <a class="link" href="information-schema.html#schemata-table" title="25.24 The INFORMATION_SCHEMA SCHEMATA Table"><code class="literal">INFORMATION_SCHEMA.SCHEMATA</code></a> table.
      </p><p>
        Example:
      </p><pre data-lang="sql" class="programlisting">
CREATE DATABASE <em class="replaceable"><code>db_name</code></em> CHARACTER SET latin1 COLLATE latin1_swedish_ci;
</pre><p>
        MySQL chooses the database character set and database collation
        in the following manner:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            If both <code class="literal">CHARACTER SET
            <em class="replaceable"><code>charset_name</code></em></code> and
            <code class="literal">COLLATE
            <em class="replaceable"><code>collation_name</code></em></code> are
            specified, character set
            <em class="replaceable"><code>charset_name</code></em> and collation
            <em class="replaceable"><code>collation_name</code></em> are used.
          </p></li><li class="listitem"><p>
            If <code class="literal">CHARACTER SET
            <em class="replaceable"><code>charset_name</code></em></code> is
            specified without <code class="literal">COLLATE</code>, character set
            <em class="replaceable"><code>charset_name</code></em> and its default
            collation are used. To see the default collation for each
            character set, use the <a class="link" href="sql-syntax.html#show-character-set" title="13.7.6.3 SHOW CHARACTER SET Syntax"><code class="literal">SHOW CHARACTER
            SET</code></a> statement or query the
            <code class="literal">INFORMATION_SCHEMA</code>
            <a class="link" href="information-schema.html#character-sets-table" title="25.2 The INFORMATION_SCHEMA CHARACTER_SETS Table"><code class="literal">CHARACTER_SETS</code></a> table.
          </p></li><li class="listitem"><p>
            If <code class="literal">COLLATE
            <em class="replaceable"><code>collation_name</code></em></code> is
            specified without <code class="literal">CHARACTER SET</code>, the
            character set associated with
            <em class="replaceable"><code>collation_name</code></em> and collation
            <em class="replaceable"><code>collation_name</code></em> are used.
          </p></li><li class="listitem"><p>
            Otherwise (neither <code class="literal">CHARACTER SET</code> nor
            <code class="literal">COLLATE</code> is specified), the server
            character set and server collation are used.
</p></li></ul>
</div>
<p>
        The character set and collation for the default database can be
        determined from the values of the
        <a class="link" href="server-administration.html#sysvar_character_set_database"><code class="literal">character_set_database</code></a> and
        <a class="link" href="server-administration.html#sysvar_collation_database"><code class="literal">collation_database</code></a> system
        variables. The server sets these variables whenever the default
        database changes. If there is no default database, the variables
        have the same value as the corresponding server-level system
        variables, <a class="link" href="server-administration.html#sysvar_character_set_server"><code class="literal">character_set_server</code></a>
        and <a class="link" href="server-administration.html#sysvar_collation_server"><code class="literal">collation_server</code></a>.
      </p><p>
        To see the default character set and collation for a given
        database, use these statements:
      </p><pre data-lang="sql" class="programlisting">
USE <em class="replaceable"><code>db_name</code></em>;
SELECT @@character_set_database, @@collation_database;
</pre><p>
        Alternatively, to display the values without changing the
        default database:
      </p><pre data-lang="sql" class="programlisting">
SELECT DEFAULT_CHARACTER_SET_NAME, DEFAULT_COLLATION_NAME
FROM INFORMATION_SCHEMA.SCHEMATA WHERE SCHEMA_NAME = '<em class="replaceable"><code>db_name</code></em>';
</pre><p>
        The database character set and collation affect these aspects of
        server operation:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            For <a class="link" href="sql-syntax.html#create-table" title="13.1.20 CREATE TABLE Syntax"><code class="literal">CREATE TABLE</code></a> statements,
            the database character set and collation are used as default
            values for table definitions if the table character set and
            collation are not specified. To override this, provide
            explicit <code class="literal">CHARACTER SET</code> and
            <code class="literal">COLLATE</code> table options.
          </p></li><li class="listitem"><p>
            For <a class="link" href="sql-syntax.html#load-data" title="13.2.7 LOAD DATA Syntax"><code class="literal">LOAD DATA</code></a> statements that
            include no <code class="literal">CHARACTER SET</code> clause, the
            server uses the character set indicated by the
            <a class="link" href="server-administration.html#sysvar_character_set_database"><code class="literal">character_set_database</code></a>
            system variable to interpret the information in the file. To
            override this, provide an explicit <code class="literal">CHARACTER
            SET</code> clause.
          </p></li><li class="listitem"><p>
            For stored routines (procedures and functions), the database
            character set and collation in effect at routine creation
            time are used as the character set and collation of
            character data parameters for which the declaration includes
            no <code class="literal">CHARACTER SET</code> or a
            <code class="literal">COLLATE</code> attribute. To override this,
            provide <code class="literal">CHARACTER SET</code> and
            <code class="literal">COLLATE</code> explicitly.
</p></li></ul>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="charset-table"></a>10.3.4 Table Character Set and Collation</h3>

</div>

</div>

</div>
<p>
        Every table has a table character set and a table collation. The
        <a class="link" href="sql-syntax.html#create-table" title="13.1.20 CREATE TABLE Syntax"><code class="literal">CREATE TABLE</code></a> and
        <a class="link" href="sql-syntax.html#alter-table" title="13.1.9 ALTER TABLE Syntax"><code class="literal">ALTER TABLE</code></a> statements have
        optional clauses for specifying the table character set and
        collation:
      </p><pre data-lang="sql" class="programlisting">
CREATE TABLE <em class="replaceable"><code>tbl_name</code></em> (<em class="replaceable"><code>column_list</code></em>)
    [[DEFAULT] CHARACTER SET <em class="replaceable"><code>charset_name</code></em>]
    [COLLATE <em class="replaceable"><code>collation_name</code></em>]]

ALTER TABLE <em class="replaceable"><code>tbl_name</code></em>
    [[DEFAULT] CHARACTER SET <em class="replaceable"><code>charset_name</code></em>]
    [COLLATE <em class="replaceable"><code>collation_name</code></em>]
</pre><p>
        Example:
      </p><pre data-lang="sql" class="programlisting">
CREATE TABLE t1 ( ... )
CHARACTER SET latin1 COLLATE latin1_danish_ci;
</pre><p>
        MySQL chooses the table character set and collation in the
        following manner:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            If both <code class="literal">CHARACTER SET
            <em class="replaceable"><code>charset_name</code></em></code> and
            <code class="literal">COLLATE
            <em class="replaceable"><code>collation_name</code></em></code> are
            specified, character set
            <em class="replaceable"><code>charset_name</code></em> and collation
            <em class="replaceable"><code>collation_name</code></em> are used.
          </p></li><li class="listitem"><p>
            If <code class="literal">CHARACTER SET
            <em class="replaceable"><code>charset_name</code></em></code> is
            specified without <code class="literal">COLLATE</code>, character set
            <em class="replaceable"><code>charset_name</code></em> and its default
            collation are used. To see the default collation for each
            character set, use the <a class="link" href="sql-syntax.html#show-character-set" title="13.7.6.3 SHOW CHARACTER SET Syntax"><code class="literal">SHOW CHARACTER
            SET</code></a> statement or query the
            <code class="literal">INFORMATION_SCHEMA</code>
            <a class="link" href="information-schema.html#character-sets-table" title="25.2 The INFORMATION_SCHEMA CHARACTER_SETS Table"><code class="literal">CHARACTER_SETS</code></a> table.
          </p></li><li class="listitem"><p>
            If <code class="literal">COLLATE
            <em class="replaceable"><code>collation_name</code></em></code> is
            specified without <code class="literal">CHARACTER SET</code>, the
            character set associated with
            <em class="replaceable"><code>collation_name</code></em> and collation
            <em class="replaceable"><code>collation_name</code></em> are used.
          </p></li><li class="listitem"><p>
            Otherwise (neither <code class="literal">CHARACTER SET</code> nor
            <code class="literal">COLLATE</code> is specified), the database
            character set and collation are used.
</p></li></ul>
</div>
<p>
        The table character set and collation are used as default values
        for column definitions if the column character set and collation
        are not specified in individual column definitions. The table
        character set and collation are MySQL extensions; there are no
        such things in standard SQL.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="charset-column"></a>10.3.5 Column Character Set and Collation</h3>

</div>

</div>

</div>
<p>
        Every <span class="quote">“<span class="quote">character</span>”</span> column (that is, a column of type
        <a class="link" href="data-types.html#char" title="11.4.1 The CHAR and VARCHAR Types"><code class="literal">CHAR</code></a>,
        <a class="link" href="data-types.html#char" title="11.4.1 The CHAR and VARCHAR Types"><code class="literal">VARCHAR</code></a>, a
        <a class="link" href="data-types.html#blob" title="11.4.3 The BLOB and TEXT Types"><code class="literal">TEXT</code></a> type, or any synonym) has a
        column character set and a column collation. Column definition
        syntax for <a class="link" href="sql-syntax.html#create-table" title="13.1.20 CREATE TABLE Syntax"><code class="literal">CREATE TABLE</code></a> and
        <a class="link" href="sql-syntax.html#alter-table" title="13.1.9 ALTER TABLE Syntax"><code class="literal">ALTER TABLE</code></a> has optional clauses
        for specifying the column character set and collation:
      </p><pre data-lang="sql" class="programlisting">
<em class="replaceable"><code>col_name</code></em> {CHAR | VARCHAR | TEXT} (<em class="replaceable"><code>col_length</code></em>)
    [CHARACTER SET <em class="replaceable"><code>charset_name</code></em>]
    [COLLATE <em class="replaceable"><code>collation_name</code></em>]
</pre><p>
        These clauses can also be used for
        <a class="link" href="data-types.html#enum" title="11.4.4 The ENUM Type"><code class="literal">ENUM</code></a> and
        <a class="link" href="data-types.html#set" title="11.4.5 The SET Type"><code class="literal">SET</code></a> columns:
      </p><pre data-lang="sql" class="programlisting">
<em class="replaceable"><code>col_name</code></em> {ENUM | SET} (<em class="replaceable"><code>val_list</code></em>)
    [CHARACTER SET <em class="replaceable"><code>charset_name</code></em>]
    [COLLATE <em class="replaceable"><code>collation_name</code></em>]
</pre><p>
        Examples:
      </p><pre data-lang="sql" class="programlisting">
CREATE TABLE t1
(
    col1 VARCHAR(5)
      CHARACTER SET latin1
      COLLATE latin1_german1_ci
);

ALTER TABLE t1 MODIFY
    col1 VARCHAR(5)
      CHARACTER SET latin1
      COLLATE latin1_swedish_ci;
</pre><p>
        MySQL chooses the column character set and collation in the
        following manner:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            If both <code class="literal">CHARACTER SET
            <em class="replaceable"><code>charset_name</code></em></code> and
            <code class="literal">COLLATE
            <em class="replaceable"><code>collation_name</code></em></code> are
            specified, character set
            <em class="replaceable"><code>charset_name</code></em> and collation
            <em class="replaceable"><code>collation_name</code></em> are used.
          </p><pre data-lang="sql" class="programlisting">
CREATE TABLE t1
(
    col1 CHAR(10) CHARACTER SET utf8 COLLATE utf8_unicode_ci
) CHARACTER SET latin1 COLLATE latin1_bin;
</pre><p>
            The character set and collation are specified for the
            column, so they are used. The column has character set
            <code class="literal">utf8</code> and collation
            <code class="literal">utf8_unicode_ci</code>.
          </p></li><li class="listitem"><p>
            If <code class="literal">CHARACTER SET
            <em class="replaceable"><code>charset_name</code></em></code> is
            specified without <code class="literal">COLLATE</code>, character set
            <em class="replaceable"><code>charset_name</code></em> and its default
            collation are used.
          </p><pre data-lang="sql" class="programlisting">
CREATE TABLE t1
(
    col1 CHAR(10) CHARACTER SET utf8
) CHARACTER SET latin1 COLLATE latin1_bin;
</pre><p>
            The character set is specified for the column, but the
            collation is not. The column has character set
            <code class="literal">utf8</code> and the default collation for
            <code class="literal">utf8</code>, which is
            <code class="literal">utf8_general_ci</code>. To see the default
            collation for each character set, use the
            <a class="link" href="sql-syntax.html#show-character-set" title="13.7.6.3 SHOW CHARACTER SET Syntax"><code class="literal">SHOW CHARACTER SET</code></a> statement
            or query the <code class="literal">INFORMATION_SCHEMA</code>
            <a class="link" href="information-schema.html#character-sets-table" title="25.2 The INFORMATION_SCHEMA CHARACTER_SETS Table"><code class="literal">CHARACTER_SETS</code></a> table.
          </p></li><li class="listitem"><p>
            If <code class="literal">COLLATE
            <em class="replaceable"><code>collation_name</code></em></code> is
            specified without <code class="literal">CHARACTER SET</code>, the
            character set associated with
            <em class="replaceable"><code>collation_name</code></em> and collation
            <em class="replaceable"><code>collation_name</code></em> are used.
          </p><pre data-lang="sql" class="programlisting">
CREATE TABLE t1
(
    col1 CHAR(10) COLLATE utf8_polish_ci
) CHARACTER SET latin1 COLLATE latin1_bin;
</pre><p>
            The collation is specified for the column, but the character
            set is not. The column has collation
            <code class="literal">utf8_polish_ci</code> and the character set is
            the one associated with the collation, which is
            <code class="literal">utf8</code>.
          </p></li><li class="listitem"><p>
            Otherwise (neither <code class="literal">CHARACTER SET</code> nor
            <code class="literal">COLLATE</code> is specified), the table
            character set and collation are used.
          </p><pre data-lang="sql" class="programlisting">
CREATE TABLE t1
(
    col1 CHAR(10)
) CHARACTER SET latin1 COLLATE latin1_bin;
</pre><p>
            Neither the character set nor collation is specified for the
            column, so the table defaults are used. The column has
            character set <code class="literal">latin1</code> and collation
            <code class="literal">latin1_bin</code>.
</p></li></ul>
</div>
<p>
        The <code class="literal">CHARACTER SET</code> and
        <code class="literal">COLLATE</code> clauses are standard SQL.
      </p><p>
        If you use <a class="link" href="sql-syntax.html#alter-table" title="13.1.9 ALTER TABLE Syntax"><code class="literal">ALTER TABLE</code></a> to convert
        a column from one character set to another, MySQL attempts to
        map the data values, but if the character sets are incompatible,
        there may be data loss.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="charset-literal"></a>10.3.6 Character String Literal Character Set and Collation</h3>

</div>

</div>

</div>
<p>
        Every character string literal has a character set and a
        collation.
      </p><p>
        For the simple statement <code class="literal">SELECT
        '<em class="replaceable"><code>string</code></em>'</code>, the string has
        the connection default character set and collation defined by
        the <a class="link" href="server-administration.html#sysvar_character_set_connection"><code class="literal">character_set_connection</code></a>
        and <a class="link" href="server-administration.html#sysvar_collation_connection"><code class="literal">collation_connection</code></a> system
        variables.
      </p><p>
        A character string literal may have an optional character set
        introducer and <code class="literal">COLLATE</code> clause, to designate
        it as a string that uses a particular character set and
        collation:
      </p><a class="indexterm" name="idm140091697831568"></a><a class="indexterm" name="idm140091697830080"></a><pre data-lang="sql" class="programlisting">
[_<em class="replaceable"><code>charset_name</code></em>]'<em class="replaceable"><code>string</code></em>' [COLLATE <em class="replaceable"><code>collation_name</code></em>]
</pre><p>
        The <code class="literal">_<em class="replaceable"><code>charset_name</code></em></code>
        expression is formally called an
        <span class="emphasis"><em>introducer</em></span>. It tells the parser, <span class="quote">“<span class="quote">the
        string that follows uses character set
        <em class="replaceable"><code>charset_name</code></em>.</span>”</span> An introducer
        does not change the string to the introducer character set like
        <a class="link" href="functions.html#function_convert"><code class="literal">CONVERT()</code></a> would do. It does not
        change the string value, although padding may occur. The
        introducer is just a signal. See
        <a class="xref" href="charset.html#charset-introducer" title="10.3.8 Character Set Introducers">Section 10.3.8, “Character Set Introducers”</a>.
      </p><p>
        Examples:
      </p><pre data-lang="sql" class="programlisting">
SELECT 'abc';
SELECT _latin1'abc';
SELECT _binary'abc';
SELECT _utf8mb4'abc' COLLATE utf8mb4_danish_ci;
</pre><p>
        Character set introducers and the <code class="literal">COLLATE</code>
        clause are implemented according to standard SQL specifications.
      </p><p>
        MySQL determines the character set and collation of a character
        string literal in the following manner:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            If both <em class="replaceable"><code>_charset_name</code></em> and
            <code class="literal">COLLATE
            <em class="replaceable"><code>collation_name</code></em></code> are
            specified, character set
            <em class="replaceable"><code>charset_name</code></em> and collation
            <em class="replaceable"><code>collation_name</code></em> are used.
            <em class="replaceable"><code>collation_name</code></em> must be a
            permitted collation for
            <em class="replaceable"><code>charset_name</code></em>.
          </p></li><li class="listitem"><p>
            If <em class="replaceable"><code>_charset_name</code></em> is specified but
            <code class="literal">COLLATE</code> is not specified, character set
            <em class="replaceable"><code>charset_name</code></em> and its default
            collation are used. To see the default collation for each
            character set, use the <a class="link" href="sql-syntax.html#show-character-set" title="13.7.6.3 SHOW CHARACTER SET Syntax"><code class="literal">SHOW CHARACTER
            SET</code></a> statement or query the
            <code class="literal">INFORMATION_SCHEMA</code>
            <a class="link" href="information-schema.html#character-sets-table" title="25.2 The INFORMATION_SCHEMA CHARACTER_SETS Table"><code class="literal">CHARACTER_SETS</code></a> table.
          </p></li><li class="listitem"><p>
            If <em class="replaceable"><code>_charset_name</code></em> is not specified
            but <code class="literal">COLLATE
            <em class="replaceable"><code>collation_name</code></em></code> is
            specified, the connection default character set given by the
            <a class="link" href="server-administration.html#sysvar_character_set_connection"><code class="literal">character_set_connection</code></a>
            system variable and collation
            <em class="replaceable"><code>collation_name</code></em> are used.
            <em class="replaceable"><code>collation_name</code></em> must be a
            permitted collation for the connection default character
            set.
          </p></li><li class="listitem"><p>
            Otherwise (neither <em class="replaceable"><code>_charset_name</code></em>
            nor <code class="literal">COLLATE
            <em class="replaceable"><code>collation_name</code></em></code> is
            specified), the connection default character set and
            collation given by the
            <a class="link" href="server-administration.html#sysvar_character_set_connection"><code class="literal">character_set_connection</code></a>
            and <a class="link" href="server-administration.html#sysvar_collation_connection"><code class="literal">collation_connection</code></a>
            system variables are used.
</p></li></ul>
</div>
<p>
        Examples:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            A nonbinary string with <code class="literal">latin1</code> character
            set and <code class="literal">latin1_german1_ci</code> collation:
          </p><pre data-lang="sql" class="programlisting">
SELECT _latin1'Müller' COLLATE latin1_german1_ci;
</pre></li><li class="listitem"><p>
            A nonbinary string with <code class="literal">utf8mb4</code> character
            set and its default collation (that is,
            <code class="literal">utf8mb4_general_ci</code>):
          </p><pre data-lang="sql" class="programlisting">
SELECT _utf8mb4'Müller';
</pre></li><li class="listitem"><p>
            A binary string with <code class="literal">binary</code> character set
            and its default collation (that is,
            <code class="literal">binary</code>):
          </p><pre data-lang="sql" class="programlisting">
SELECT _binary'Müller';
</pre></li><li class="listitem"><p>
            A nonbinary string with the connection default character set
            and <code class="literal">utf8mb4_general_ci</code> collation (fails
            if the connection character set is not
            <code class="literal">utf8mb4</code>):
          </p><pre data-lang="sql" class="programlisting">
SELECT 'Müller' COLLATE utf8mb4_general_ci;
</pre></li><li class="listitem"><p>
            A string with the connection default character set and
            collation:
          </p><pre data-lang="sql" class="programlisting">
SELECT 'Müller';
</pre></li></ul>
</div>
<p>
        An introducer indicates the character set for the following
        string, but does not change how the parser performs escape
        processing within the string. Escapes are always interpreted by
        the parser according to the character set given by
        <a class="link" href="server-administration.html#sysvar_character_set_connection"><code class="literal">character_set_connection</code></a>.
      </p><p>
        The following examples show that escape processing occurs using
        <a class="link" href="server-administration.html#sysvar_character_set_connection"><code class="literal">character_set_connection</code></a> even
        in the presence of an introducer. The examples use
        <a class="link" href="sql-syntax.html#set-names" title="13.7.5.3 SET NAMES Syntax"><code class="literal">SET NAMES</code></a> (which changes
        <a class="link" href="server-administration.html#sysvar_character_set_connection"><code class="literal">character_set_connection</code></a>, as
        discussed in <a class="xref" href="charset.html#charset-connection" title="10.4 Connection Character Sets and Collations">Section 10.4, “Connection Character Sets and Collations”</a>), and display
        the resulting strings using the
        <a class="link" href="functions.html#function_hex"><code class="literal">HEX()</code></a> function so that the exact
        string contents can be seen.
      </p><p>
        Example 1:
      </p><pre data-lang="sql" class="programlisting">
mysql&gt; <strong class="userinput"><code>SET NAMES latin1;</code></strong>
mysql&gt; <strong class="userinput"><code>SELECT HEX('à\n'), HEX(_sjis'à\n');</code></strong>
+------------+-----------------+
| HEX('à\n')  | HEX(_sjis'à\n')  |
+------------+-----------------+
| E00A       | E00A            |
+------------+-----------------+
</pre><p>
        Here, <code class="literal">à</code> (hexadecimal value
        <code class="literal">E0</code>) is followed by <code class="literal">\n</code>, the
        escape sequence for newline. The escape sequence is interpreted
        using the
        <a class="link" href="server-administration.html#sysvar_character_set_connection"><code class="literal">character_set_connection</code></a> value
        of <code class="literal">latin1</code> to produce a literal newline
        (hexadecimal value <code class="literal">0A</code>). This happens even for
        the second string. That is, the <code class="literal">_sjis</code>
        introducer does not affect the parser's escape processing.
      </p><p>
        Example 2:
      </p><pre data-lang="sql" class="programlisting">
mysql&gt; <strong class="userinput"><code>SET NAMES sjis;</code></strong>
mysql&gt; <strong class="userinput"><code>SELECT HEX('à\n'), HEX(_latin1'à\n');</code></strong>
+------------+-------------------+
| HEX('à\n')  | HEX(_latin1'à\n')  |
+------------+-------------------+
| E05C6E     | E05C6E            |
+------------+-------------------+
</pre><p>
        Here, <a class="link" href="server-administration.html#sysvar_character_set_connection"><code class="literal">character_set_connection</code></a>
        is <code class="literal">sjis</code>, a character set in which the
        sequence of <code class="literal">à</code> followed by
        <code class="literal">\</code> (hexadecimal values <code class="literal">05</code>
        and <code class="literal">5C</code>) is a valid multibyte character.
        Hence, the first two bytes of the string are interpreted as a
        single <code class="literal">sjis</code> character, and the
        <code class="literal">\</code> is not interpreted as an escape character.
        The following <code class="literal">n</code> (hexadecimal value
        <code class="literal">6E</code>) is not interpreted as part of an escape
        sequence. This is true even for the second string; the
        <code class="literal">_latin1</code> introducer does not affect escape
        processing.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="charset-national"></a>10.3.7 The National Character Set</h3>

</div>

</div>

</div>
<p>
        Standard SQL defines <a class="link" href="data-types.html#char" title="11.4.1 The CHAR and VARCHAR Types"><code class="literal">NCHAR</code></a> or
        <a class="link" href="data-types.html#char" title="11.4.1 The CHAR and VARCHAR Types"><code class="literal">NATIONAL CHAR</code></a> as a way to
        indicate that a <a class="link" href="data-types.html#char" title="11.4.1 The CHAR and VARCHAR Types"><code class="literal">CHAR</code></a> column
        should use some predefined character set. MySQL uses
        <code class="literal">utf8</code> as this predefined character set. For
        example, these data type declarations are equivalent:
      </p><pre data-lang="sql" class="programlisting">
CHAR(10) CHARACTER SET utf8
NATIONAL CHARACTER(10)
NCHAR(10)
</pre><p>
        As are these:
      </p><pre data-lang="sql" class="programlisting">
VARCHAR(10) CHARACTER SET utf8
NATIONAL VARCHAR(10)
NVARCHAR(10)
NCHAR VARCHAR(10)
NATIONAL CHARACTER VARYING(10)
NATIONAL CHAR VARYING(10)
</pre><p>
        You can use
        <code class="literal">N'<em class="replaceable"><code>literal</code></em>'</code> (or
        <code class="literal">n'<em class="replaceable"><code>literal</code></em>'</code>) to
        create a string in the national character set. These statements
        are equivalent:
      </p><pre data-lang="sql" class="programlisting">
SELECT N'some text';
SELECT n'some text';
SELECT _utf8'some text';
</pre>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="charset-introducer"></a>10.3.8 Character Set Introducers</h3>

</div>

</div>

</div>
<a class="indexterm" name="idm140091697739088"></a><a class="indexterm" name="idm140091697737632"></a><p>
        A character string literal, hexadecimal literal, or bit-value
        literal may have an optional character set introducer and
        <code class="literal">COLLATE</code> clause, to designate it as a string
        that uses a particular character set and collation:
      </p><pre data-lang="sql" class="programlisting">
[_<em class="replaceable"><code>charset_name</code></em>] <em class="replaceable"><code>literal</code></em> [COLLATE <em class="replaceable"><code>collation_name</code></em>]
</pre><p>
        The <code class="literal">_<em class="replaceable"><code>charset_name</code></em></code>
        expression is formally called an
        <span class="emphasis"><em>introducer</em></span>. It tells the parser, <span class="quote">“<span class="quote">the
        string that follows uses character set
        <em class="replaceable"><code>charset_name</code></em>.</span>”</span> An introducer
        does not change the string to the introducer character set like
        <a class="link" href="functions.html#function_convert"><code class="literal">CONVERT()</code></a> would do. It does not
        change the string value, although padding may occur. The
        introducer is just a signal.
      </p><p>
        For character string literals, space between the introducer and
        the string is permitted but optional.
      </p><p>
        Examples:
      </p><pre data-lang="sql" class="programlisting">
SELECT 'abc';
SELECT _latin1'abc';
SELECT _binary'abc';
SELECT _utf8mb4'abc' COLLATE utf8mb4_danish_ci;

SELECT _latin1 X'4D7953514C';
SELECT _utf8mb4 0x4D7953514C COLLATE utf8mb4_danish_ci;

SELECT _latin1 b'1000001';
SELECT _utf8mb4 0b1000001 COLLATE utf8mb4_danish_ci;
</pre><p>
        Character set introducers and the <code class="literal">COLLATE</code>
        clause are implemented according to standard SQL specifications.
      </p><p>
        Character string literals can be designated as binary strings by
        using the <code class="literal">_binary</code> introducer. Hexadecimal
        literals and bit-value literals are binary strings by default,
        so <code class="literal">_binary</code> is permitted, but normally
        unnecessary. <code class="literal">_binary</code> may be useful to
        preserve a hexadecimal or bit literal as a binary string in
        contexts for which the literal is otherwise treated as a number.
        For example, bit operations permit numeric or binary string
        arguments in MySQL 8.0 and higher, but treat
        hexadecimal and bit literals as numbers by default. To
        explicitly specify binary string context for such literals, use
        a <code class="literal">_binary</code> introducer for at least one of the
        arguments:
      </p><pre data-lang="sql" class="programlisting">
mysql&gt; <strong class="userinput"><code>SET @v1 = X'000D' | X'0BC0';</code></strong>
mysql&gt; <strong class="userinput"><code>SET @v2 = _binary X'000D' | X'0BC0';</code></strong>
mysql&gt; <strong class="userinput"><code>SELECT HEX(@v1), HEX(@v2);</code></strong>
+----------+----------+
| HEX(@v1) | HEX(@v2) |
+----------+----------+
| BCD      | 0BCD     |
+----------+----------+
</pre><p>
        The displayed result appears similar for both bit operations,
        but the result without <code class="literal">_binary</code> is a
        <code class="literal">BIGINT</code> value, whereas the result with
        <code class="literal">_binary</code> is a binary string. Due to the
        difference in result types, the displayed values differ:
        High-order 0 digits are not displayed for the numeric result.
      </p><p>
        MySQL determines the character set and collation of a character
        string literal, hexadecimal literal, or bit-value literal in the
        following manner:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            If both <em class="replaceable"><code>_charset_name</code></em> and
            <code class="literal">COLLATE
            <em class="replaceable"><code>collation_name</code></em></code> are
            specified, character set
            <em class="replaceable"><code>charset_name</code></em> and collation
            <em class="replaceable"><code>collation_name</code></em> are used.
            <em class="replaceable"><code>collation_name</code></em> must be a
            permitted collation for
            <em class="replaceable"><code>charset_name</code></em>.
          </p></li><li class="listitem"><p>
            If <em class="replaceable"><code>_charset_name</code></em> is specified but
            <code class="literal">COLLATE</code> is not specified, character set
            <em class="replaceable"><code>charset_name</code></em> and its default
            collation are used. To see the default collation for each
            character set, use the <a class="link" href="sql-syntax.html#show-character-set" title="13.7.6.3 SHOW CHARACTER SET Syntax"><code class="literal">SHOW CHARACTER
            SET</code></a> statement or query the
            <code class="literal">INFORMATION_SCHEMA</code>
            <a class="link" href="information-schema.html#character-sets-table" title="25.2 The INFORMATION_SCHEMA CHARACTER_SETS Table"><code class="literal">CHARACTER_SETS</code></a> table.
          </p></li><li class="listitem"><p>
            If <em class="replaceable"><code>_charset_name</code></em> is not specified
            but <code class="literal">COLLATE
            <em class="replaceable"><code>collation_name</code></em></code> is
            specified:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
                For a character string literal, the connection default
                character set given by the
                <a class="link" href="server-administration.html#sysvar_character_set_connection"><code class="literal">character_set_connection</code></a>
                system variable and collation
                <em class="replaceable"><code>collation_name</code></em> are used.
                <em class="replaceable"><code>collation_name</code></em> must be a
                permitted collation for the connection default character
                set.
              </p></li><li class="listitem"><p>
                For a hexadecimal literal or bit-value literal, the only
                permitted collation is <code class="literal">binary</code> because
                these types of literals are binary strings by default.
</p></li></ul>
</div>
</li><li class="listitem"><p>
            Otherwise (neither <em class="replaceable"><code>_charset_name</code></em>
            nor <code class="literal">COLLATE
            <em class="replaceable"><code>collation_name</code></em></code> is
            specified):
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
                For a character string literal, the connection default
                character set and collation given by the
                <a class="link" href="server-administration.html#sysvar_character_set_connection"><code class="literal">character_set_connection</code></a>
                and
                <a class="link" href="server-administration.html#sysvar_collation_connection"><code class="literal">collation_connection</code></a>
                system variables are used.
              </p></li><li class="listitem"><p>
                For a hexadecimal literal or bit-value literal, the
                character set and collation are
                <code class="literal">binary</code>.
</p></li></ul>
</div>
</li></ul>
</div>
<p>
        Examples:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            Nonbinary strings with <code class="literal">latin1</code> character
            set and <code class="literal">latin1_german1_ci</code> collation:
          </p><pre data-lang="sql" class="programlisting">
SELECT _latin1'Müller' COLLATE latin1_german1_ci;
SELECT _latin1 X'0A0D' COLLATE latin1_german1_ci;
SELECT _latin1 b'0110' COLLATE latin1_german1_ci;
</pre></li><li class="listitem"><p>
            Nonbinary strings with <code class="literal">utf8mb4</code> character
            set and its default collation (that is,
            <code class="literal">utf8mb4_0900_ai_ci</code>):
          </p><pre data-lang="sql" class="programlisting">
SELECT _utf8mb4'Müller';
SELECT _utf8mb4 X'0A0D';
SELECT _utf8mb4 b'0110';
</pre></li><li class="listitem"><p>
            Binary strings with <code class="literal">binary</code> character set
            and its default collation (that is,
            <code class="literal">binary</code>):
          </p><pre data-lang="sql" class="programlisting">
SELECT _binary'Müller';
SELECT X'0A0D';
SELECT b'0110';
</pre><p>
            The hexadecimal literal and bit-value literal need no
            introducer because they are binary strings by default.
          </p></li><li class="listitem"><p>
            A nonbinary string with the connection default character set
            and <code class="literal">utf8mb4_general_ci</code> collation (fails
            if the connection character set is not
            <code class="literal">utf8mb4</code>):
          </p><pre data-lang="sql" class="programlisting">
SELECT 'Müller' COLLATE utf8mb4_general_ci;
</pre><p>
            This construction (<code class="literal">COLLATE</code> only) does not
            work for hexadecimal literals or bit literals because their
            character set is <code class="literal">binary</code> no matter the
            connection character set, and <code class="literal">binary</code> is
            not compatible with the
            <code class="literal">utf8mb4_general_ci</code> collation. The only
            permitted <code class="literal">COLLATE</code> clause in the absence
            of an introducer is <code class="literal">COLLATE binary</code>.
          </p></li><li class="listitem"><p>
            A string with the connection default character set and
            collation:
          </p><pre data-lang="sql" class="programlisting">
SELECT 'Müller';
</pre></li></ul>
</div>
<p>
        For character set literals, an introducer indicates the
        character set for the following string, but does not change how
        the parser performs escape processing within the string. Escapes
        are always interpreted by the parser according to the character
        set given by
        <a class="link" href="server-administration.html#sysvar_character_set_connection"><code class="literal">character_set_connection</code></a>. For
        additional discussion and examples, see
        <a class="xref" href="charset.html#charset-literal" title="10.3.6 Character String Literal Character Set and Collation">Section 10.3.6, “Character String Literal Character Set and Collation”</a>.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="charset-examples"></a>10.3.9 Examples of Character Set and Collation Assignment</h3>

</div>

</div>

</div>
<p>
        The following examples show how MySQL determines default
        character set and collation values.
      </p><p>
        <span class="bold"><strong>Example 1: Table and Column
        Definition</strong></span>
      </p><pre data-lang="sql" class="programlisting">
CREATE TABLE t1
(
    c1 CHAR(10) CHARACTER SET latin1 COLLATE latin1_german1_ci
) DEFAULT CHARACTER SET latin2 COLLATE latin2_bin;
</pre><p>
        Here we have a column with a <code class="literal">latin1</code> character
        set and a <code class="literal">latin1_german1_ci</code> collation. The
        definition is explicit, so that is straightforward. Notice that
        there is no problem with storing a <code class="literal">latin1</code>
        column in a <code class="literal">latin2</code> table.
      </p><p>
        <span class="bold"><strong>Example 2: Table and Column
        Definition</strong></span>
      </p><pre data-lang="sql" class="programlisting">
CREATE TABLE t1
(
    c1 CHAR(10) CHARACTER SET latin1
) DEFAULT CHARACTER SET latin1 COLLATE latin1_danish_ci;
</pre><p>
        This time we have a column with a <code class="literal">latin1</code>
        character set and a default collation. Although it might seem
        natural, the default collation is not taken from the table
        level. Instead, because the default collation for
        <code class="literal">latin1</code> is always
        <code class="literal">latin1_swedish_ci</code>, column
        <code class="literal">c1</code> has a collation of
        <code class="literal">latin1_swedish_ci</code> (not
        <code class="literal">latin1_danish_ci</code>).
      </p><p>
        <span class="bold"><strong>Example 3: Table and Column
        Definition</strong></span>
      </p><pre data-lang="sql" class="programlisting">
CREATE TABLE t1
(
    c1 CHAR(10)
) DEFAULT CHARACTER SET latin1 COLLATE latin1_danish_ci;
</pre><p>
        We have a column with a default character set and a default
        collation. In this circumstance, MySQL checks the table level to
        determine the column character set and collation. Consequently,
        the character set for column <code class="literal">c1</code> is
        <code class="literal">latin1</code> and its collation is
        <code class="literal">latin1_danish_ci</code>.
      </p><p>
        <span class="bold"><strong>Example 4: Database, Table, and Column
        Definition</strong></span>
      </p><pre data-lang="sql" class="programlisting">
CREATE DATABASE d1
    DEFAULT CHARACTER SET latin2 COLLATE latin2_czech_ci;
USE d1;
CREATE TABLE t1
(
    c1 CHAR(10)
);
</pre><p>
        We create a column without specifying its character set and
        collation. We're also not specifying a character set and a
        collation at the table level. In this circumstance, MySQL checks
        the database level to determine the table settings, which
        thereafter become the column settings.) Consequently, the
        character set for column <code class="literal">c1</code> is
        <code class="literal">latin2</code> and its collation is
        <code class="literal">latin2_czech_ci</code>.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="charset-compatibility"></a>10.3.10 Compatibility with Other DBMSs</h3>

</div>

</div>

</div>
<p>
        For MaxDB compatibility these two statements are the same:
      </p><pre data-lang="sql" class="programlisting">
CREATE TABLE t1 (f1 CHAR(<em class="replaceable"><code>N</code></em>) UNICODE);
CREATE TABLE t1 (f1 CHAR(<em class="replaceable"><code>N</code></em>) CHARACTER SET ucs2);
</pre>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both"><a name="charset-connection"></a>10.4 Connection Character Sets and Collations</h2>

</div>

</div>

</div>
<a class="indexterm" name="idm140091697635232"></a><a class="indexterm" name="idm140091697633808"></a><p>
      A <span class="quote">“<span class="quote">connection</span>”</span> is what a client program makes when it
      connects to the server, to begin a session within which it
      interacts with the server. The client sends SQL statements, such
      as queries, over the session connection. The server sends
      responses, such as result sets or error messages, over the
      connection back to the client.
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><a class="xref" href="charset.html#charset-connection-system-variables" title="Connection Character Set and Collation System Variables">Connection Character Set and Collation System Variables</a></p></li><li class="listitem"><p><a class="xref" href="charset.html#charset-connection-impermissible-client-charset" title="Impermissible Client Character Sets">Impermissible Client Character Sets</a></p></li><li class="listitem"><p><a class="xref" href="charset.html#charset-connection-client-configuration" title="Client Program Connection Character Set Configuration">Client Program Connection Character Set Configuration</a></p></li><li class="listitem"><p><a class="xref" href="charset.html#charset-connection-sql-statements" title="SQL Statements for Connection Character Set Configuration">SQL Statements for Connection Character Set Configuration</a></p></li><li class="listitem"><p><a class="xref" href="charset.html#charset-connection-error-handling" title="Connection Character Set Error Handling">Connection Character Set Error Handling</a></p></li></ul>
</div>

<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h3 class="title"><a name="charset-connection-system-variables"></a>Connection Character Set and Collation System Variables</h3>

</div>

</div>

</div>
<p>
        Several character set and collation system variables relate to a
        client's interaction with the server. Some of these have been
        mentioned in earlier sections:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            The <a class="link" href="server-administration.html#sysvar_character_set_server"><code class="literal">character_set_server</code></a>
            and <a class="link" href="server-administration.html#sysvar_collation_server"><code class="literal">collation_server</code></a> system
            variables indicate the server character set and collation.
            See <a class="xref" href="charset.html#charset-server" title="10.3.2 Server Character Set and Collation">Section 10.3.2, “Server Character Set and Collation”</a>.
          </p></li><li class="listitem"><p>
            The <a class="link" href="server-administration.html#sysvar_character_set_database"><code class="literal">character_set_database</code></a>
            and <a class="link" href="server-administration.html#sysvar_collation_database"><code class="literal">collation_database</code></a>
            system variables indicate the character set and collation of
            the default database. See
            <a class="xref" href="charset.html#charset-database" title="10.3.3 Database Character Set and Collation">Section 10.3.3, “Database Character Set and Collation”</a>.
</p></li></ul>
</div>
<p>
        Additional character set and collation system variables are
        involved in handling traffic for the connection between a client
        and the server. Every client has session-specific
        connection-related character set and collation system variables.
        These session system variable values are initialized at connect
        time, but can be changed within the session.
      </p><p>
        Several questions about character set and collation handling for
        client connections can be answered in terms of system variables:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            What character set are statements in when they leave the
            client?
          </p><p>
            The server takes the
            <a class="link" href="server-administration.html#sysvar_character_set_client"><code class="literal">character_set_client</code></a> system
            variable to be the character set in which statements are
            sent by the client.
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Note
</div>
<p>
              Some character sets cannot be used as the client character
              set. See
              <a class="xref" href="charset.html#charset-connection-impermissible-client-charset" title="Impermissible Client Character Sets">Impermissible Client Character Sets</a>.
</p>
</div>
</li><li class="listitem"><p>
            What character set should the server translate statements to
            after receiving them?
          </p><p>
            To determine this, the server uses the
            <a class="link" href="server-administration.html#sysvar_character_set_connection"><code class="literal">character_set_connection</code></a>
            and <a class="link" href="server-administration.html#sysvar_collation_connection"><code class="literal">collation_connection</code></a>
            system variables:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
                The server converts statements sent by the client from
                <a class="link" href="server-administration.html#sysvar_character_set_client"><code class="literal">character_set_client</code></a> to
                <a class="link" href="server-administration.html#sysvar_character_set_connection"><code class="literal">character_set_connection</code></a>.
                Exception: For string literals that have an introducer
                such as <code class="literal">_utf8mb4</code> or
                <code class="literal">_latin2</code>, the introducer determines
                the character set. See
                <a class="xref" href="charset.html#charset-introducer" title="10.3.8 Character Set Introducers">Section 10.3.8, “Character Set Introducers”</a>.
              </p></li><li class="listitem"><p>
                <a class="link" href="server-administration.html#sysvar_collation_connection"><code class="literal">collation_connection</code></a> is
                important for comparisons of literal strings. For
                comparisons of strings with column values,
                <a class="link" href="server-administration.html#sysvar_collation_connection"><code class="literal">collation_connection</code></a>
                does not matter because columns have their own
                collation, which has a higher collation precedence (see
                <a class="xref" href="charset.html#charset-collation-coercibility" title="10.8.4 Collation Coercibility in Expressions">Section 10.8.4, “Collation Coercibility in Expressions”</a>).
</p></li></ul>
</div>
</li><li class="listitem"><p>
            What character set should the server translate query results
            to before shipping them back to the client?
          </p><p>
            The <a class="link" href="server-administration.html#sysvar_character_set_results"><code class="literal">character_set_results</code></a>
            system variable indicates the character set in which the
            server returns query results to the client. This includes
            result data such as column values, result metadata such as
            column names, and error messages.
          </p><p>
            To tell the server to perform no conversion of result sets
            or error messages, set
            <a class="link" href="server-administration.html#sysvar_character_set_results"><code class="literal">character_set_results</code></a> to
            <code class="literal">NULL</code> or <code class="literal">binary</code>:
          </p><pre data-lang="sql" class="programlisting">
SET character_set_results = NULL;
SET character_set_results = binary;
</pre><p>
            For more information about character sets and error
            messages, see <a class="xref" href="charset.html#charset-errors" title="10.6 Error Message Character Set">Section 10.6, “Error Message Character Set”</a>.
</p></li></ul>
</div>
<p>
        To see the values of the character set and collation system
        variables that apply to the current session, use this statement:
      </p><pre data-lang="sql" class="programlisting">
SELECT * FROM performance_schema.session_variables
WHERE VARIABLE_NAME IN (
'character_set_client', 'character_set_connection',
'character_set_results', 'collation_connection'
) ORDER BY VARIABLE_NAME;
</pre><p>
        The following simpler statements also display the connection
        variables, but include other related variables as well. They can
        be useful to see <span class="emphasis"><em>all</em></span> character set and
        collation system variables:
      </p><pre data-lang="sql" class="programlisting">
SHOW SESSION VARIABLES LIKE 'character\_set\_%';
SHOW SESSION VARIABLES LIKE 'collation\_%';
</pre><p>
        Clients can fine-tune the settings for these variables, or
        depend on the defaults (in which case, you can skip the rest of
        this section). If you do not use the defaults, you must change
        the character settings <span class="emphasis"><em>for each connection to the
        server.</em></span>
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h3 class="title"><a name="charset-connection-impermissible-client-charset"></a>Impermissible Client Character Sets</h3>

</div>

</div>

</div>
<a class="indexterm" name="idm140091697580400"></a><a class="indexterm" name="idm140091697578912"></a><a class="indexterm" name="idm140091697577424"></a><a class="indexterm" name="idm140091697575936"></a><p>
        The <a class="link" href="server-administration.html#sysvar_character_set_client"><code class="literal">character_set_client</code></a> system
        variable cannot be set to certain character sets:
      </p><pre data-lang="simple" class="programlisting">
ucs2
utf16
utf16le
utf32
</pre><p>
        Attempting to use any of those character sets as the client
        character set produces an error:
      </p><pre data-lang="sql" class="programlisting">
mysql&gt; <strong class="userinput"><code>SET character_set_client = 'ucs2';</code></strong>
ERROR 1231 (42000): Variable 'character_set_client'
can't be set to the value of 'ucs2'
</pre><p>
        The same error occurs if any of those character sets are used in
        the following contexts, all of which result in an attempt to set
        <a class="link" href="server-administration.html#sysvar_character_set_client"><code class="literal">character_set_client</code></a> to the
        named character set:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            The
            <a class="link" href="programs.html#option_mysql_default-character-set"><code class="option">--default-character-set=<em class="replaceable"><code>charset_name</code></em></code></a>
            command option used by MySQL client programs such as
            <a class="link" href="programs.html#mysql" title="4.5.1 mysql — The MySQL Command-Line Client"><span class="command"><strong>mysql</strong></span></a> and <a class="link" href="programs.html#mysqladmin" title="4.5.2 mysqladmin — Client for Administering a MySQL Server"><span class="command"><strong>mysqladmin</strong></span></a>.
          </p></li><li class="listitem"><p>
            The <a class="link" href="sql-syntax.html#set-names" title="13.7.5.3 SET NAMES Syntax"><code class="literal">SET NAMES
            '<em class="replaceable"><code>charset_name</code></em>'</code></a>
            statement.
          </p></li><li class="listitem"><p>
            The <a class="link" href="sql-syntax.html#set-character-set" title="13.7.5.2 SET CHARACTER SET Syntax"><code class="literal">SET
            CHARACTER SET
            '<em class="replaceable"><code>charset_name</code></em>'</code></a>
            statement.
</p></li></ul>
</div>

</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h3 class="title"><a name="charset-connection-client-configuration"></a>Client Program Connection Character Set Configuration</h3>

</div>

</div>

</div>
<p>
        When a client connects to the server, it indicates which
        character set it wants to use for communication with the server.
        (Actually, the client indicates the default collation for that
        character set, from which the server can determine the character
        set.) The server uses this information to set the
        <a class="link" href="server-administration.html#sysvar_character_set_client"><code class="literal">character_set_client</code></a>,
        <a class="link" href="server-administration.html#sysvar_character_set_results"><code class="literal">character_set_results</code></a>,
        <a class="link" href="server-administration.html#sysvar_character_set_connection"><code class="literal">character_set_connection</code></a> system
        variables to the character set, and
        <a class="link" href="server-administration.html#sysvar_collation_connection"><code class="literal">collation_connection</code></a> to the
        character set default collation. In effect, the server performs
        the equivalent of a <a class="link" href="sql-syntax.html#set-names" title="13.7.5.3 SET NAMES Syntax"><code class="literal">SET NAMES</code></a>
        operation.
      </p><p>
        If the server does not support the requested character set or
        collation, it falls back to using the server character set and
        collation to configure the connection. For additional detail
        about this fallback behavior, see
        <a class="xref" href="charset.html#charset-connection-error-handling" title="Connection Character Set Error Handling">Connection Character Set Error Handling</a>.
      </p><p>
        The <a class="link" href="programs.html#mysql" title="4.5.1 mysql — The MySQL Command-Line Client"><span class="command"><strong>mysql</strong></span></a>, <a class="link" href="programs.html#mysqladmin" title="4.5.2 mysqladmin — Client for Administering a MySQL Server"><span class="command"><strong>mysqladmin</strong></span></a>,
        <a class="link" href="programs.html#mysqlcheck" title="4.5.3 mysqlcheck — A Table Maintenance Program"><span class="command"><strong>mysqlcheck</strong></span></a>, <a class="link" href="programs.html#mysqlimport" title="4.5.5 mysqlimport — A Data Import Program"><span class="command"><strong>mysqlimport</strong></span></a>,
        and <a class="link" href="programs.html#mysqlshow" title="4.5.7 mysqlshow — Display Database, Table, and Column Information"><span class="command"><strong>mysqlshow</strong></span></a> client programs determine the
        default character set to use as follows:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            In the absence of other information, each client uses the
            compiled-in default character set, usually
            <code class="literal">utf8mb4</code>.
          </p></li><li class="listitem"><p>
            Each client can autodetect which character set to use based
            on the operating system setting, such as the value of the
            <code class="literal">LANG</code> or <code class="literal">LC_ALL</code> locale
            environment variable on Unix systems or the code page
            setting on Windows systems. For systems on which the locale
            is available from the OS, the client uses it to set the
            default character set rather than using the compiled-in
            default. For example, setting <code class="literal">LANG</code> to
            <code class="literal">ru_RU.KOI8-R</code> causes the
            <code class="literal">koi8r</code> character set to be used. Thus,
            users can configure the locale in their environment for use
            by MySQL clients.
          </p><p>
            The OS character set is mapped to the closest MySQL
            character set if there is no exact match. If the client does
            not support the matching character set, it uses the
            compiled-in default. For example, <code class="literal">utf8</code>
            and <code class="literal">utf-8</code> map to
            <code class="literal">utf8mb4</code>, and <code class="literal">ucs2</code> is
            not supported as a connection character set, so it maps to
            the compiled-in default.
          </p><p>
            C applications can use character set autodetection based on
            the OS setting by invoking
            <a class="link" href="connectors-apis.html#mysql-options" title="28.7.7.50 mysql_options()"><code class="literal">mysql_options()</code></a> as follows
            before connecting to the server:
          </p><pre data-lang="c" class="programlisting">
mysql_options(mysql,
              MYSQL_SET_CHARSET_NAME,
              MYSQL_AUTODETECT_CHARSET_NAME);
</pre></li><li class="listitem"><p>
            Each client supports a
            <a class="link" href="programs.html#option_mysql_default-character-set"><code class="option">--default-character-set</code></a>
            option, which enables users to specify the character set
            explicitly to override whatever default the client otherwise
            determines.
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Note
</div>
<p>
              Some character sets cannot be used as the client character
              set. Attempting to use them with
              <a class="link" href="programs.html#option_mysql_default-character-set"><code class="option">--default-character-set</code></a>
              produces an error. See
              <a class="xref" href="charset.html#charset-connection-impermissible-client-charset" title="Impermissible Client Character Sets">Impermissible Client Character Sets</a>.
</p>
</div>
</li></ul>
</div>
<p>
        With the <a class="link" href="programs.html#mysql" title="4.5.1 mysql — The MySQL Command-Line Client"><span class="command"><strong>mysql</strong></span></a> client, to use a character set
        different from the default, you could explicitly execute a
        <a class="link" href="sql-syntax.html#set-names" title="13.7.5.3 SET NAMES Syntax"><code class="literal">SET NAMES</code></a> statement every time
        you connect to the server (see
        <a class="xref" href="charset.html#charset-connection-client-configuration" title="Client Program Connection Character Set Configuration">Client Program Connection Character Set Configuration</a>). To
        accomplish the same result more easily, specify the character
        set in your option file. For example, the following option file
        setting changes the three connection-related character set
        system variables set to <code class="literal">koi8r</code> each time you
        invoke <a class="link" href="programs.html#mysql" title="4.5.1 mysql — The MySQL Command-Line Client"><span class="command"><strong>mysql</strong></span></a>:
      </p><pre data-lang="ini" class="programlisting">
[mysql]
default-character-set=koi8r
</pre><p>
        If you are using the <a class="link" href="programs.html#mysql" title="4.5.1 mysql — The MySQL Command-Line Client"><span class="command"><strong>mysql</strong></span></a> client with
        auto-reconnect enabled (which is not recommended), it is
        preferable to use the <code class="literal">charset</code> command rather
        than <a class="link" href="sql-syntax.html#set-names" title="13.7.5.3 SET NAMES Syntax"><code class="literal">SET NAMES</code></a>. For example:
      </p><pre data-lang="sql" class="programlisting">
mysql&gt; <strong class="userinput"><code>charset koi8r</code></strong>
Charset changed
</pre><p>
        The <code class="literal">charset</code> command issues a
        <a class="link" href="sql-syntax.html#set-names" title="13.7.5.3 SET NAMES Syntax"><code class="literal">SET NAMES</code></a> statement, and also
        changes the default character set that <a class="link" href="programs.html#mysql" title="4.5.1 mysql — The MySQL Command-Line Client"><span class="command"><strong>mysql</strong></span></a>
        uses when it reconnects after the connection has dropped.
      </p><p>
        When configuration client programs, you must also consider the
        environment within which they execute. See
        <a class="xref" href="charset.html#charset-applications" title="10.5 Configuring Application Character Set and Collation">Section 10.5, “Configuring Application Character Set and Collation”</a>.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h3 class="title"><a name="charset-connection-sql-statements"></a>SQL Statements for Connection Character Set Configuration</h3>

</div>

</div>

</div>
<p>
        After a connection has been established, clients can change the
        character set and collation system variables for the current
        session. These variables can be changed individually using
        <a class="link" href="sql-syntax.html#set-statement" title="13.7.5 SET Syntax"><code class="literal">SET</code></a>
        statements, but two more convenient statements affect the
        connection-related character set sytem variables as a group:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            <code class="literal">SET NAMES '<em class="replaceable"><code>charset_name</code></em>'
            [COLLATE
            '<em class="replaceable"><code>collation_name</code></em>']</code>
          </p><p>
            <a class="link" href="sql-syntax.html#set-names" title="13.7.5.3 SET NAMES Syntax"><code class="literal">SET NAMES</code></a> indicates what
            character set the client will use to send SQL statements to
            the server. Thus,
            <a class="link" href="sql-syntax.html#set-names" title="13.7.5.3 SET NAMES Syntax"><code class="literal">SET NAMES
            'cp1251'</code></a> tells the server, <span class="quote">“<span class="quote">future incoming
            messages from this client are in character set
            <code class="literal">cp1251</code>.</span>”</span> It also specifies the
            character set that the server should use for sending results
            back to the client. (For example, it indicates what
            character set to use for column values if you use a
            <a class="link" href="sql-syntax.html#select" title="13.2.10 SELECT Syntax"><code class="literal">SELECT</code></a> statement that
            produces a result set.)
          </p><p>
            A <a class="link" href="sql-syntax.html#set-names" title="13.7.5.3 SET NAMES Syntax"><code class="literal">SET NAMES
            '<em class="replaceable"><code>charset_name</code></em>'</code></a>
            statement is equivalent to these three statements:
          </p><pre data-lang="sql" class="programlisting">
SET character_set_client = <em class="replaceable"><code>charset_name</code></em>;
SET character_set_results = <em class="replaceable"><code>charset_name</code></em>;
SET character_set_connection = <em class="replaceable"><code>charset_name</code></em>;
</pre><p>
            Setting
            <a class="link" href="server-administration.html#sysvar_character_set_connection"><code class="literal">character_set_connection</code></a> to
            <em class="replaceable"><code>charset_name</code></em> also implicitly sets
            <a class="link" href="server-administration.html#sysvar_collation_connection"><code class="literal">collation_connection</code></a> to the
            default collation for
            <em class="replaceable"><code>charset_name</code></em>. It is unnecessary
            to set that collation explicitly. To specify a particular
            collation to use for
            <a class="link" href="server-administration.html#sysvar_collation_connection"><code class="literal">collation_connection</code></a>, add a
            <code class="literal">COLLATE</code> clause:
          </p><pre data-lang="sql" class="programlisting">
SET NAMES '<em class="replaceable"><code>charset_name</code></em>' COLLATE '<em class="replaceable"><code>collation_name</code></em>'
</pre></li><li class="listitem"><p>
            <code class="literal">SET CHARACTER SET
            '<em class="replaceable"><code>charset_name</code></em></code>'
          </p><p>
            <a class="link" href="sql-syntax.html#set-character-set" title="13.7.5.2 SET CHARACTER SET Syntax"><code class="literal">SET CHARACTER SET</code></a> is similar
            to <a class="link" href="sql-syntax.html#set-names" title="13.7.5.3 SET NAMES Syntax"><code class="literal">SET NAMES</code></a> but sets
            <a class="link" href="server-administration.html#sysvar_character_set_connection"><code class="literal">character_set_connection</code></a>
            and <a class="link" href="server-administration.html#sysvar_collation_connection"><code class="literal">collation_connection</code></a> to
            <a class="link" href="server-administration.html#sysvar_character_set_database"><code class="literal">character_set_database</code></a> and
            <a class="link" href="server-administration.html#sysvar_collation_database"><code class="literal">collation_database</code></a> (which,
            as mentioned previously, indicate the character set and
            collation of the default database).
          </p><p>
            A <a class="link" href="sql-syntax.html#set-character-set" title="13.7.5.2 SET CHARACTER SET Syntax"><code class="literal">SET
            CHARACTER SET
            <em class="replaceable"><code>charset_name</code></em></code></a> statement
            is equivalent to these three statements:
          </p><pre data-lang="sql" class="programlisting">
SET character_set_client = <em class="replaceable"><code>charset_name</code></em>;
SET character_set_results = <em class="replaceable"><code>charset_name</code></em>;
SET collation_connection = @@collation_database;
</pre><p>
            Setting
            <a class="link" href="server-administration.html#sysvar_collation_connection"><code class="literal">collation_connection</code></a> also
            implicitly sets
            <a class="link" href="server-administration.html#sysvar_character_set_connection"><code class="literal">character_set_connection</code></a> to
            the character set associated with the collation (equivalent
            to executing <code class="literal">SET character_set_connection =
            @@character_set_database</code>). It is unnecessary to
            set
            <a class="link" href="server-administration.html#sysvar_character_set_connection"><code class="literal">character_set_connection</code></a>
            explicitly.
</p></li></ul>
</div>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<div class="admon-title">
Note
</div>
<p>
          Some character sets cannot be used as the client character
          set. Attempting to use them with <a class="link" href="sql-syntax.html#set-names" title="13.7.5.3 SET NAMES Syntax"><code class="literal">SET
          NAMES</code></a> or <a class="link" href="sql-syntax.html#set-character-set" title="13.7.5.2 SET CHARACTER SET Syntax"><code class="literal">SET CHARACTER
          SET</code></a> produces an error. See
          <a class="xref" href="charset.html#charset-connection-impermissible-client-charset" title="Impermissible Client Character Sets">Impermissible Client Character Sets</a>.
</p>
</div>
<p>
        Example: Suppose that <code class="literal">column1</code> is defined as
        <code class="literal">CHAR(5) CHARACTER SET latin2</code>. If you do not
        say <a class="link" href="sql-syntax.html#set-names" title="13.7.5.3 SET NAMES Syntax"><code class="literal">SET NAMES</code></a> or
        <a class="link" href="sql-syntax.html#set-character-set" title="13.7.5.2 SET CHARACTER SET Syntax"><code class="literal">SET CHARACTER SET</code></a>, then for
        <code class="literal">SELECT column1 FROM t</code>, the server sends back
        all the values for <code class="literal">column1</code> using the
        character set that the client specified when it connected. On
        the other hand, if you say <code class="literal">SET NAMES 'latin1'</code>
        or <code class="literal">SET CHARACTER SET 'latin1'</code> before issuing
        the <a class="link" href="sql-syntax.html#select" title="13.2.10 SELECT Syntax"><code class="literal">SELECT</code></a> statement, the server
        converts the <code class="literal">latin2</code> values to
        <code class="literal">latin1</code> just before sending results back.
        Conversion may be lossy for characters that are not in both
        character sets.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h3 class="title"><a name="charset-connection-error-handling"></a>Connection Character Set Error Handling</h3>

</div>

</div>

</div>
<p>
        Attempts to use an inappropriate connection character set or
        collation can produce an error, or cause the server to fall back
        to its default character set and collation for a given
        connection. This section describes problems that can occur when
        configuring the connection character set. These problems can
        occur when establishing a connection or when changing the
        character set within an established connection.
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><a class="xref" href="charset.html#charset-connection-error-handling-connect-time" title="Connect-Time Error Handling">Connect-Time Error Handling</a></p></li><li class="listitem"><p><a class="xref" href="charset.html#charset-connection-error-handling-runtime" title="Runtime Error Handling">Runtime Error Handling</a></p></li></ul>
</div>
<h4><a name="charset-connection-error-handling-connect-time"></a>Connect-Time Error Handling</h4>
<p>
        Some character sets cannot be used as the client character set;
        see
        <a class="xref" href="charset.html#charset-connection-impermissible-client-charset" title="Impermissible Client Character Sets">Impermissible Client Character Sets</a>.
        If you specify a character set that is valid but not permitted
        as a client character set, the server returns an error:
      </p><pre data-lang="terminal" class="programlisting">
shell&gt; <strong class="userinput"><code>mysql --default-character-set=ucs2</code></strong>
ERROR 1231 (42000): Variable 'character_set_client' can't be set to
the value of 'ucs2'
</pre><p>
        If you specify a character set that the client does not
        recognize, it produces an error:
      </p><pre data-lang="terminal" class="programlisting">
shell&gt; <strong class="userinput"><code>mysql --default-character-set=bogus</code></strong>
mysql: Character set 'bogus' is not a compiled character set and is
not specified in the '/usr/local/mysql/share/charsets/Index.xml' file
ERROR 2019 (HY000): Can't initialize character set bogus
(path: /usr/local/mysql/share/charsets/)
</pre><p>
        If you specify a character set that the client recognizes but
        the server does not, the server falls back to its default
        character set and collation. Suppose that the server is
        configured to use <code class="literal">latin1</code> and
        <code class="literal">latin1_swedish_ci</code> as its defaults, and that
        it does not recognize <code class="literal">gb18030</code> as a valid
        character set. A client that specifies
        <a class="link" href="programs.html#option_mysql_default-character-set"><code class="option">--default-character-set=gb18030</code></a> is
        able to connect to the server, but the resulting character set
        is not what the client wants:
      </p><pre data-lang="sql" class="programlisting">
mysql&gt; <strong class="userinput"><code>SHOW SESSION VARIABLES LIKE 'character\_set\_%';</code></strong>
+--------------------------+--------+
| Variable_name            | Value  |
+--------------------------+--------+
| character_set_client     | latin1 |
| character_set_connection | latin1 |
...
| character_set_results    | latin1 |
...
+--------------------------+--------+
mysql&gt; <strong class="userinput"><code>SHOW SESSION VARIABLES LIKE 'collation_connection';</code></strong>
+----------------------+-------------------+
| Variable_name        | Value             |
+----------------------+-------------------+
| collation_connection | latin1_swedish_ci |
+----------------------+-------------------+
</pre><p>
        You can see that the connection system variables have been set
        to reflect a character set and collation of
        <code class="literal">latin1</code> and
        <code class="literal">latin1_swedish_ci</code>. This occurs because the
        server cannot satisfy the client character set request and falls
        back to its defaults.
      </p><p>
        In this case, the client cannot use the character set that it
        wants because the server does not support it. The client must
        either be willing to use a different character set, or connect
        to a different server that supports the desired character set.
      </p><p>
        The same problem occurs in a more subtle context: When the
        client tells the server to use a character set that the server
        recognizes, but the default collation for that character set on
        the client side is not known on the server side. This occurs,
        for example, when a MySQL 8.0 client wants to connect to a MySQL
        5.7 server using <code class="literal">utf8mb4</code> as the client
        character set. A client that specifies
        <a class="link" href="programs.html#option_mysql_default-character-set"><code class="option">--default-character-set=utf8mb4</code></a> is
        able to connect to the server. However, as in the previous
        example, the server falls back to its default character set and
        collation, not what the client requested:
      </p><pre data-lang="sql" class="programlisting">
mysql&gt; <strong class="userinput"><code>SHOW SESSION VARIABLES LIKE 'character\_set\_%';</code></strong>
+--------------------------+--------+
| Variable_name            | Value  |
+--------------------------+--------+
| character_set_client     | latin1 |
| character_set_connection | latin1 |
...
| character_set_results    | latin1 |
...
+--------------------------+--------+
mysql&gt; <strong class="userinput"><code>SHOW SESSION VARIABLES LIKE 'collation_connection';</code></strong>
+----------------------+-------------------+
| Variable_name        | Value             |
+----------------------+-------------------+
| collation_connection | latin1_swedish_ci |
+----------------------+-------------------+
</pre><p>
        Why does this occur? After all, <code class="literal">utf8mb4</code> is
        known to the 8.0 client and the 5.7 server, so both of them
        recognize it. To understand this behavior, it is necessary to
        understand that when the client tells the server which character
        set it wants to use, it really tells the server the default
        collation for that character set. Therefore, the aforementioned
        behavior occurs due to a combination of factors:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            The default collation for <code class="literal">utf8mb4</code> differs
            between MySQL 5.7 and 8.0
            (<code class="literal">utf8mb4_general_ci</code> for 5.7,
            <code class="literal">utf8mb4_0900_ai_ci</code> for 8.0).
          </p></li><li class="listitem"><p>
            When the 8.0 client requests a character set of
            <code class="literal">utf8mb4</code>, what it sends to the server is
            the default 8.0 <code class="literal">utf8mb4</code> collation; that
            is, the <code class="literal">utf8mb4_0900_ai_ci</code>.
          </p></li><li class="listitem"><p>
            <code class="literal">utf8mb4_0900_ai_ci</code> is implemented only as
            of MySQL 8.0, so the 5.7 server does not recognize it.
          </p></li><li class="listitem"><p>
            Because the 5.7 server does not recognize
            <code class="literal">utf8mb4_0900_ai_ci</code>, it cannot satisfy the
            client character set request, and falls back to its default
            character set and collation (<code class="literal">latin1</code> and
            <code class="literal">latin1_swedish_ci</code>).
</p></li></ul>
</div>
<p>
        In this case, the client can still use
        <code class="literal">utf8mb4</code> by issuing a <code class="literal">SET NAMES
        'utf8mb4'</code> statement after connecting. The resulting
        collation is the 5.7 default <code class="literal">utf8mb4</code>
        collation; that is, <code class="literal">utf8mb4_general_ci</code>. If
        the client additionally wants a collation of
        <code class="literal">utf8mb4_0900_ai_ci</code>, it cannot achieve that
        because the server does not recognize that collation. The client
        must either be willing to use a different
        <code class="literal">utf8mb4</code> collation, or connect to a server
        from MySQL 8.0 or higher.
</p>
<h4><a name="charset-connection-error-handling-runtime"></a>Runtime Error Handling</h4>
<p>
        Within an established connection, the client can request a
        change of connection character set and collation with
        <a class="link" href="sql-syntax.html#set-names" title="13.7.5.3 SET NAMES Syntax"><code class="literal">SET NAMES</code></a> or
        <a class="link" href="sql-syntax.html#set-character-set" title="13.7.5.2 SET CHARACTER SET Syntax"><code class="literal">SET CHARACTER SET</code></a>.
      </p><p>
        Some character sets cannot be used as the client character set;
        see
        <a class="xref" href="charset.html#charset-connection-impermissible-client-charset" title="Impermissible Client Character Sets">Impermissible Client Character Sets</a>.
        If you specify a character set that is valid but not permitted
        as a client character set, the server returns an error:
      </p><pre data-lang="sql" class="programlisting">
mysql&gt; <strong class="userinput"><code>SET NAMES 'ucs2';</code></strong>
ERROR 1231 (42000): Variable 'character_set_client' can't be set to
the value of 'ucs2'
</pre><p>
        If the server does not recognize the character set (or the
        collation), it produces an error:
      </p><pre data-lang="sql" class="programlisting">
mysql&gt; <strong class="userinput"><code>SET NAMES 'bogus';</code></strong>
ERROR 1115 (42000): Unknown character set: 'bogus'

mysql&gt; <strong class="userinput"><code>SET NAMES 'utf8mb4' COLLATE 'bogus';</code></strong>
ERROR 1273 (HY000): Unknown collation: 'bogus'
</pre>
<div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Tip
</div>
<p>
          A client that wants to verify whether its requested character
          set was honored by the server can execute the following
          statement after connecting and checking that the result is the
          expected character set:
        </p><pre data-lang="sql" class="programlisting">
SELECT @@character_set_client;
</pre>
</div>

</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both"><a name="charset-applications"></a>10.5 Configuring Application Character Set and Collation</h2>

</div>

</div>

</div>
<a class="indexterm" name="idm140091697389552"></a><p>
      For applications that store data using the default MySQL character
      set and collation (<code class="literal">utf8mb4</code>,
      <code class="literal">utf8mb4_0900_ai_ci</code>), no special configuration
      should be needed. If applications require data storage using a
      different character set or collation, you can configure character
      set information several ways:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          Specify character settings per database. For example,
          applications that use one database might use the default of
          <code class="literal">utf8mb4</code>, whereas applications that use
          another database might use <code class="literal">sjis</code>.
        </p></li><li class="listitem"><p>
          Specify character settings at server startup. This causes the
          server to use the given settings for all applications that do
          not make other arrangements.
        </p></li><li class="listitem"><p>
          Specify character settings at configuration time, if you build
          MySQL from source. This causes the server to use the given
          settings as the defaults for all applications, without having
          to specify them at server startup.
</p></li></ul>
</div>
<p>
      When different applications require different character settings,
      the per-database technique provides a good deal of flexibility. If
      most or all applications use the same character set, specifying
      character settings at server startup or configuration time may be
      most convenient.
    </p><p>
      For the per-database or server-startup techniques, the settings
      control the character set for data storage. Applications must also
      tell the server which character set to use for client/server
      communications, as described in the following instructions.
    </p><p>
      The examples shown here assume use of the
      <code class="literal">latin1</code> character set and
      <code class="literal">latin1_swedish_ci</code> collation in particular
      contexts as an alternative to the defaults of
      <code class="literal">utf8mb4</code> and
      <code class="literal">utf8mb4_0900_ai_ci</code>.
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><b>Specify character settings per database. </b>
            To create a database such that its tables will use a given
            default character set and collation for data storage, use a
            <a class="link" href="sql-syntax.html#create-database" title="13.1.12 CREATE DATABASE Syntax"><code class="literal">CREATE DATABASE</code></a> statement
            like this:
          </p><pre data-lang="sql" class="programlisting">
CREATE DATABASE mydb
  CHARACTER SET latin1
  COLLATE latin1_swedish_ci;
</pre><p>
          Tables created in the database will use
          <code class="literal">latin1</code> and
          <code class="literal">latin1_swedish_ci</code> by default for any
          character columns.
        </p><p>
          Applications that use the database should also configure their
          connection to the server each time they connect. This can be
          done by executing a <code class="literal">SET NAMES 'latin1'</code>
          statement after connecting. The statement can be used
          regardless of connection method (the <a class="link" href="programs.html#mysql" title="4.5.1 mysql — The MySQL Command-Line Client"><span class="command"><strong>mysql</strong></span></a>
          client, PHP scripts, and so forth).
        </p><p>
          In some cases, it may be possible to configure the connection
          to use the desired character set some other way. For example,
          to connect using <a class="link" href="programs.html#mysql" title="4.5.1 mysql — The MySQL Command-Line Client"><span class="command"><strong>mysql</strong></span></a>, you can specify the
          <a class="link" href="programs.html#option_mysql_default-character-set"><code class="option">--default-character-set=latin1</code></a>
          command-line option to achieve the same effect as <code class="literal">SET
          NAMES 'latin1'</code>.
        </p><p>
          For more information about configuring client connections, see
          <a class="xref" href="charset.html#charset-connection" title="10.4 Connection Character Sets and Collations">Section 10.4, “Connection Character Sets and Collations”</a>.
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Note
</div>
<p>
            If you use <a class="link" href="sql-syntax.html#alter-database" title="13.1.2 ALTER DATABASE Syntax"><code class="literal">ALTER DATABASE</code></a> to
            change the database default character set or collation,
            existing stored routines in the database that use those
            defaults must be dropped and recreated so that they use the
            new defaults. (In a stored routine, variables with character
            data types use the database defaults if the character set or
            collation are not specified explicitly. See
            <a class="xref" href="sql-syntax.html#create-procedure" title="13.1.17 CREATE PROCEDURE and CREATE FUNCTION Syntax">Section 13.1.17, “CREATE PROCEDURE and CREATE FUNCTION Syntax”</a>.)
</p>
</div>
</li><li class="listitem"><p><b>Specify character settings at server startup. </b>
            To select a character set and collation at server startup,
            use the
            <a class="link" href="server-administration.html#sysvar_character_set_server"><code class="option">--character-set-server</code></a> and
            <a class="link" href="server-administration.html#sysvar_collation_server"><code class="option">--collation-server</code></a> options.
            For example, to specify the options in an option file,
            include these lines:
          </p><pre data-lang="ini" class="programlisting">
[mysqld]
character-set-server=latin1
collation-server=latin1_swedish_ci
</pre><p>
          These settings apply server-wide and apply as the defaults for
          databases created by any application, and for tables created
          in those databases.
        </p><p>
          It is still necessary for applications to configure their
          connection using <a class="link" href="sql-syntax.html#set-names" title="13.7.5.3 SET NAMES Syntax"><code class="literal">SET NAMES</code></a> or
          equivalent after they connect, as described previously. You
          might be tempted to start the server with the
          <a class="link" href="server-administration.html#sysvar_init_connect"><code class="option">--init_connect="SET NAMES
          'latin1'"</code></a> option to cause <a class="link" href="sql-syntax.html#set-names" title="13.7.5.3 SET NAMES Syntax"><code class="literal">SET
          NAMES</code></a> to be executed automatically for each client
          that connects. However, this may yield inconsistent results
          because the <a class="link" href="server-administration.html#sysvar_init_connect"><code class="literal">init_connect</code></a>
          value is not executed for users who have the
          <a class="link" href="security.html#priv_connection-admin"><code class="literal">CONNECTION_ADMIN</code></a> or
          <a class="link" href="security.html#priv_super"><code class="literal">SUPER</code></a> privilege.
        </p></li><li class="listitem"><p><b>Specify character settings at MySQL configuration time. </b>
            To select a character set and collation if you configure and
            build MySQL from source, use the
            <a class="link" href="installing.html#option_cmake_default_charset"><code class="option">DEFAULT_CHARSET</code></a> and
            <a class="link" href="installing.html#option_cmake_default_collation"><code class="option">DEFAULT_COLLATION</code></a>
            <span class="command"><strong>CMake</strong></span> options:
          </p><pre data-lang="terminal" class="programlisting">
cmake . -DDEFAULT_CHARSET=latin1 \
  -DDEFAULT_COLLATION=latin1_swedish_ci
</pre><p>
          The resulting server uses <code class="literal">latin1</code> and
          <code class="literal">latin1_swedish_ci</code> as the default for
          databases and tables and for client connections. It is
          unnecessary to use
          <a class="link" href="server-administration.html#sysvar_character_set_server"><code class="option">--character-set-server</code></a> and
          <a class="link" href="server-administration.html#sysvar_collation_server"><code class="option">--collation-server</code></a> to specify
          those defaults at server startup. It is also unnecessary for
          applications to configure their connection using
          <a class="link" href="sql-syntax.html#set-names" title="13.7.5.3 SET NAMES Syntax"><code class="literal">SET NAMES</code></a> or equivalent after
          they connect to the server.
</p></li></ul>
</div>
<p>
      Regardless of how you configure the MySQL character set for
      application use, you must also consider the environment within
      which those applications execute. For example, if you will send
      statements using UTF-8 text taken from a file that you create in
      an editor, you should edit the file with the locale of your
      environment set to UTF-8 so that the file encoding is correct and
      so that the operating system handles it correctly. If you use the
      <a class="link" href="programs.html#mysql" title="4.5.1 mysql — The MySQL Command-Line Client"><span class="command"><strong>mysql</strong></span></a> client from within a terminal window, the
      window must be configured to use UTF-8 or characters may not
      display properly. For a script that executes in a Web environment,
      the script must handle character encoding properly for its
      interaction with the MySQL server, and it must generate pages that
      correctly indicate the encoding so that browsers know how to
      display the content of the pages. For example, you can include
      this <code class="literal">&lt;meta&gt;</code> tag within your
      <code class="literal">&lt;head&gt;</code> element:
    </p><pre data-lang="html" class="programlisting">
&lt;meta http-equiv="Content-Type" content="text/html; charset=utf-8" /&gt;
</pre>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both"><a name="charset-errors"></a>10.6 Error Message Character Set</h2>

</div>

</div>

</div>
<p>
      This section describes how the MySQL server uses character sets
      for constructing error messages. For information about the
      language of error messages (rather than the character set), see
      <a class="xref" href="charset.html#error-message-language" title="10.11 Setting the Error Message Language">Section 10.11, “Setting the Error Message Language”</a>. For general information
      about configuring error logging, see <a class="xref" href="server-administration.html#error-log" title="5.4.2 The Error Log">Section 5.4.2, “The Error Log”</a>.
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><a class="xref" href="charset.html#charset-errors-construction" title="Character Set for Error Message Construction">Character Set for Error Message Construction</a></p></li><li class="listitem"><p><a class="xref" href="charset.html#charset-errors-disposition" title="Character Set for Error Message Disposition">Character Set for Error Message Disposition</a></p></li></ul>
</div>

<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h3 class="title"><a name="charset-errors-construction"></a>Character Set for Error Message Construction</h3>

</div>

</div>

</div>
<p>
        The server constructs error messages as follows:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            The message template uses UTF-8
            (<code class="literal">utf8mb3</code>).
          </p></li><li class="listitem"><p>
            Parameters in the message template are replaced with values
            that apply to a specific error occurrence:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
                Identifiers such as table or column names use UTF-8
                internally so they are copied as is.
              </p></li><li class="listitem"><p>
                Character (nonbinary) string values are converted from
                their character set to UTF-8.
              </p></li><li class="listitem"><p>
                Binary string values are copied as is for bytes in the
                range <code class="literal">0x20</code> to
                <code class="literal">0x7E</code>, and using <code class="literal">\x</code>
                hexadecimal encoding for bytes outside that range. For
                example, if a duplicate-key error occurs for an attempt
                to insert <code class="literal">0x41CF9F</code> into a
                <a class="link" href="data-types.html#binary-varbinary" title="11.4.2 The BINARY and VARBINARY Types"><code class="literal">VARBINARY</code></a> unique column,
                the resulting error message uses UTF-8 with some bytes
                hexadecimal encoded:
              </p><pre data-lang="none" class="programlisting">
Duplicate entry 'A\xC3\x9F' for key 1
</pre></li></ul>
</div>
</li></ul>
</div>

</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h3 class="title"><a name="charset-errors-disposition"></a>Character Set for Error Message Disposition</h3>

</div>

</div>

</div>
<p>
        An error message, once constructed, can be written by the server
        to the error log or sent to clients:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            If the server writes the error message to the error log, it
            writes it in UTF-8, as constructed, without conversion to
            another character set.
          </p></li><li class="listitem"><p>
            If the server sends the error message to a client program,
            the server converts it from UTF-8 to the character set
            specified by the
            <a class="link" href="server-administration.html#sysvar_character_set_results"><code class="literal">character_set_results</code></a>
            system variable. If
            <a class="link" href="server-administration.html#sysvar_character_set_results"><code class="literal">character_set_results</code></a> has a
            value of <code class="literal">NULL</code> or
            <code class="literal">binary</code>, no conversion occurs. No
            conversion occurs if the variable value is
            <code class="literal">utf8mb3</code> or <code class="literal">utf8mb4</code>,
            either, because those character sets have a repertoire that
            includes all UTF-8 characters used in message construction.
          </p><p>
            If characters cannot be represented in
            <a class="link" href="server-administration.html#sysvar_character_set_results"><code class="literal">character_set_results</code></a>, some
            encoding may occur during the conversion. The encoding uses
            Unicode code point values:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
                Characters in the Basic Multilingual Plane (BMP) range
                (<code class="literal">0x0000</code> to <code class="literal">0xFFFF</code>)
                are written using
                <code class="literal">\<em class="replaceable"><code>nnnn</code></em></code>
                notation.
              </p></li><li class="listitem"><p>
                Characters outside the BMP range
                (<code class="literal">0x10000</code> to
                <code class="literal">0x10FFFF</code>) are written using
                <code class="literal">\+<em class="replaceable"><code>nnnnnn</code></em></code>
                notation.
</p></li></ul>
</div>
<p>
            Clients can set
            <a class="link" href="server-administration.html#sysvar_character_set_results"><code class="literal">character_set_results</code></a> to
            control the character set in which they receive error
            messages. The variable can be set directly, or indirectly by
            means such as <a class="link" href="sql-syntax.html#set-names" title="13.7.5.3 SET NAMES Syntax"><code class="literal">SET NAMES</code></a>. For
            more information about
            <a class="link" href="server-administration.html#sysvar_character_set_results"><code class="literal">character_set_results</code></a>, see
            <a class="xref" href="charset.html#charset-connection" title="10.4 Connection Character Sets and Collations">Section 10.4, “Connection Character Sets and Collations”</a>.
</p></li></ul>
</div>

</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both"><a name="charset-conversion"></a>10.7 Column Character Set Conversion</h2>

</div>

</div>

</div>
<p>
      To convert a binary or nonbinary string column to use a particular
      character set, use <a class="link" href="sql-syntax.html#alter-table" title="13.1.9 ALTER TABLE Syntax"><code class="literal">ALTER TABLE</code></a>. For
      successful conversion to occur, one of the following conditions
      must apply:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          If the column has a binary data type
          (<a class="link" href="data-types.html#binary-varbinary" title="11.4.2 The BINARY and VARBINARY Types"><code class="literal">BINARY</code></a>,
          <a class="link" href="data-types.html#binary-varbinary" title="11.4.2 The BINARY and VARBINARY Types"><code class="literal">VARBINARY</code></a>,
          <a class="link" href="data-types.html#blob" title="11.4.3 The BLOB and TEXT Types"><code class="literal">BLOB</code></a>), all the values that it
          contains must be encoded using a single character set (the
          character set you're converting the column to). If you use a
          binary column to store information in multiple character sets,
          MySQL has no way to know which values use which character set
          and cannot convert the data properly.
        </p></li><li class="listitem"><p>
          If the column has a nonbinary data type
          (<a class="link" href="data-types.html#char" title="11.4.1 The CHAR and VARCHAR Types"><code class="literal">CHAR</code></a>,
          <a class="link" href="data-types.html#char" title="11.4.1 The CHAR and VARCHAR Types"><code class="literal">VARCHAR</code></a>,
          <a class="link" href="data-types.html#blob" title="11.4.3 The BLOB and TEXT Types"><code class="literal">TEXT</code></a>), its contents should be
          encoded in the column character set, not some other character
          set. If the contents are encoded in a different character set,
          you can convert the column to use a binary data type first,
          and then to a nonbinary column with the desired character set.
</p></li></ul>
</div>
<p>
      Suppose that a table <code class="literal">t</code> has a binary column
      named <code class="literal">col1</code> defined as
      <code class="literal">VARBINARY(50)</code>. Assuming that the information in
      the column is encoded using a single character set, you can
      convert it to a nonbinary column that has that character set. For
      example, if <code class="literal">col1</code> contains binary data
      representing characters in the <code class="literal">greek</code> character
      set, you can convert it as follows:
    </p><pre data-lang="sql" class="programlisting">
ALTER TABLE t MODIFY col1 VARCHAR(50) CHARACTER SET greek;
</pre><p>
      If your original column has a type of
      <code class="literal">BINARY(50)</code>, you could convert it to
      <code class="literal">CHAR(50)</code>, but the resulting values will be
      padded with <code class="literal">0x00</code> bytes at the end, which may be
      undesirable. To remove these bytes, use the
      <a class="link" href="functions.html#function_trim"><code class="literal">TRIM()</code></a> function:
    </p><pre data-lang="sql" class="programlisting">
UPDATE t SET col1 = TRIM(TRAILING 0x00 FROM col1);
</pre><p>
      Suppose that table <code class="literal">t</code> has a nonbinary column
      named <code class="literal">col1</code> defined as <code class="literal">CHAR(50)
      CHARACTER SET latin1</code> but you want to convert it to use
      <code class="literal">utf8</code> so that you can store values from many
      languages. The following statement accomplishes this:
    </p><pre data-lang="sql" class="programlisting">
ALTER TABLE t MODIFY col1 CHAR(50) CHARACTER SET utf8;
</pre><p>
      Conversion may be lossy if the column contains characters that are
      not in both character sets.
    </p><p>
      A special case occurs if you have old tables from before MySQL 4.1
      where a nonbinary column contains values that actually are encoded
      in a character set different from the server's default character
      set. For example, an application might have stored
      <code class="literal">sjis</code> values in a column, even though MySQL's
      default character set was different. It is possible to convert the
      column to use the proper character set but an additional step is
      required. Suppose that the server's default character set was
      <code class="literal">latin1</code> and <code class="literal">col1</code> is defined
      as <code class="literal">CHAR(50)</code> but its contents are
      <code class="literal">sjis</code> values. The first step is to convert the
      column to a binary data type, which removes the existing character
      set information without performing any character conversion:
    </p><pre data-lang="sql" class="programlisting">
ALTER TABLE t MODIFY col1 BLOB;
</pre><p>
      The next step is to convert the column to a nonbinary data type
      with the proper character set:
    </p><pre data-lang="sql" class="programlisting">
ALTER TABLE t MODIFY col1 CHAR(50) CHARACTER SET sjis;
</pre><p>
      This procedure requires that the table not have been modified
      already with statements such as
      <a class="link" href="sql-syntax.html#insert" title="13.2.6 INSERT Syntax"><code class="literal">INSERT</code></a> or
      <a class="link" href="sql-syntax.html#update" title="13.2.12 UPDATE Syntax"><code class="literal">UPDATE</code></a> after an upgrade to MySQL
      4.1 or higher. In that case, MySQL would store new values in the
      column using <code class="literal">latin1</code>, and the column will
      contain a mix of <code class="literal">sjis</code> and
      <code class="literal">latin1</code> values and cannot be converted properly.
    </p><p>
      If you specified attributes when creating a column initially, you
      should also specify them when altering the table with
      <a class="link" href="sql-syntax.html#alter-table" title="13.1.9 ALTER TABLE Syntax"><code class="literal">ALTER TABLE</code></a>. For example, if you
      specified <code class="literal">NOT NULL</code> and an explicit
      <code class="literal">DEFAULT</code> value, you should also provide them in
      the <a class="link" href="sql-syntax.html#alter-table" title="13.1.9 ALTER TABLE Syntax"><code class="literal">ALTER TABLE</code></a> statement.
      Otherwise, the resulting column definition will not include those
      attributes.
    </p><p>
      To convert all character columns in a table, the <code class="literal">ALTER
      TABLE ... CONVERT TO CHARACTER SET
      <em class="replaceable"><code>charset</code></em></code> statement may be
      useful. See <a class="xref" href="sql-syntax.html#alter-table" title="13.1.9 ALTER TABLE Syntax">Section 13.1.9, “ALTER TABLE Syntax”</a>.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both"><a name="charset-collations"></a>10.8 Collation Issues</h2>

</div>

</div>

</div>
<div class="toc">
<dl class="toc"><dt><span class="section"><a href="charset.html#charset-collate">10.8.1 Using COLLATE in SQL Statements</a></span></dt><dt><span class="section"><a href="charset.html#charset-collate-precedence">10.8.2 COLLATE Clause Precedence</a></span></dt><dt><span class="section"><a href="charset.html#charset-collation-compatibility">10.8.3 Character Set and Collation Compatibility</a></span></dt><dt><span class="section"><a href="charset.html#charset-collation-coercibility">10.8.4 Collation Coercibility in Expressions</a></span></dt><dt><span class="section"><a href="charset.html#charset-binary-collations">10.8.5 The binary Collation Compared to _bin Collations</a></span></dt><dt><span class="section"><a href="charset.html#charset-collation-effect">10.8.6 Examples of the Effect of Collation</a></span></dt><dt><span class="section"><a href="charset.html#charset-collation-information-schema">10.8.7 Using Collation in INFORMATION_SCHEMA Searches</a></span></dt></dl>
</div>
<p>
      The following sections discuss various aspects of character set
      collations.
</p>
<div class="section">

<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="charset-collate"></a>10.8.1 Using COLLATE in SQL Statements</h3>
</div>
</div>
</div>
<p>
        With the <code class="literal">COLLATE</code> clause, you can override
        whatever the default collation is for a comparison.
        <code class="literal">COLLATE</code> may be used in various parts of SQL
        statements. Here are some examples:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            With <code class="literal">ORDER BY</code>:
          </p><pre data-lang="sql" class="programlisting">
SELECT k
FROM t1
ORDER BY k COLLATE latin1_german2_ci;
</pre></li><li class="listitem"><p>
            With <code class="literal">AS</code>:
          </p><pre data-lang="sql" class="programlisting">
SELECT k COLLATE latin1_german2_ci AS k1
FROM t1
ORDER BY k1;
</pre></li><li class="listitem"><p>
            With <code class="literal">GROUP BY</code>:
          </p><pre data-lang="sql" class="programlisting">
SELECT k
FROM t1
GROUP BY k COLLATE latin1_german2_ci;
</pre></li><li class="listitem"><p>
            With aggregate functions:
          </p><pre data-lang="sql" class="programlisting">
SELECT MAX(k COLLATE latin1_german2_ci)
FROM t1;
</pre></li><li class="listitem"><p>
            With <code class="literal">DISTINCT</code>:
          </p><pre data-lang="sql" class="programlisting">
SELECT DISTINCT k COLLATE latin1_german2_ci
FROM t1;
</pre></li><li class="listitem"><p>
            With <code class="literal">WHERE</code>:
          </p><pre data-lang="sql" class="programlisting">
     SELECT *
     FROM t1
     WHERE _latin1 'Müller' COLLATE latin1_german2_ci = k;
</pre><pre data-lang="sql" class="programlisting">
     SELECT *
     FROM t1
     WHERE k LIKE _latin1 'Müller' COLLATE latin1_german2_ci;
</pre></li><li class="listitem"><p>
            With <code class="literal">HAVING</code>:
          </p><pre data-lang="sql" class="programlisting">
SELECT k
FROM t1
GROUP BY k
HAVING k = _latin1 'Müller' COLLATE latin1_german2_ci;
</pre></li></ul>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="charset-collate-precedence"></a>10.8.2 COLLATE Clause Precedence</h3>

</div>

</div>

</div>
<p>
        The <code class="literal">COLLATE</code> clause has high precedence
        (higher than <a class="link" href="functions.html#operator_or"><code class="literal">||</code></a>), so
        the following two expressions are equivalent:
      </p><pre data-lang="sql" class="programlisting">
x || y COLLATE z
x || (y COLLATE z)
</pre>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="charset-collation-compatibility"></a>10.8.3 Character Set and Collation Compatibility</h3>

</div>

</div>

</div>
<p>
        Each character set has one or more collations, but each
        collation is associated with one and only one character set.
        Therefore, the following statement causes an error message
        because the <code class="literal">latin2_bin</code> collation is not legal
        with the <code class="literal">latin1</code> character set:
      </p><pre data-lang="sql" class="programlisting">
mysql&gt; <strong class="userinput"><code>SELECT _latin1 'x' COLLATE latin2_bin;</code></strong>
ERROR 1253 (42000): COLLATION 'latin2_bin' is not valid
for CHARACTER SET 'latin1'
</pre>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="charset-collation-coercibility"></a>10.8.4 Collation Coercibility in Expressions</h3>

</div>

</div>

</div>
<a class="indexterm" name="idm140091697206032"></a><a class="indexterm" name="idm140091697204544"></a><p>
        In the great majority of statements, it is obvious what
        collation MySQL uses to resolve a comparison operation. For
        example, in the following cases, it should be clear that the
        collation is the collation of column <code class="literal">x</code>:
      </p><pre data-lang="sql" class="programlisting">
SELECT x FROM T ORDER BY x;
SELECT x FROM T WHERE x = x;
SELECT DISTINCT x FROM T;
</pre><p>
        However, with multiple operands, there can be ambiguity. For
        example:
      </p><pre data-lang="sql" class="programlisting">
SELECT x FROM T WHERE x = 'Y';
</pre><p>
        Should the comparison use the collation of the column
        <code class="literal">x</code>, or of the string literal
        <code class="literal">'Y'</code>? Both <code class="literal">x</code> and
        <code class="literal">'Y'</code> have collations, so which collation takes
        precedence?
      </p><p>
        A mix of collations may also occur in contexts other than
        comparison. For example, a multiple-argument concatenation
        operation such as <a class="link" href="functions.html#function_concat"><code class="literal">CONCAT(x,'Y')</code></a>
        combines its arguments to produce a single string. What
        collation should the result have?
      </p><p>
        To resolve questions like these, MySQL checks whether the
        collation of one item can be coerced to the collation of the
        other. MySQL assigns coercibility values as follows:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            An explicit <code class="literal">COLLATE</code> clause has a
            coercibility of 0 (not coercible at all).
          </p></li><li class="listitem"><p>
            The concatenation of two strings with different collations
            has a coercibility of 1.
          </p></li><li class="listitem"><p>
            The collation of a column or a stored routine parameter or
            local variable has a coercibility of 2.
          </p></li><li class="listitem"><p>
            A <span class="quote">“<span class="quote">system constant</span>”</span> (the string returned by
            functions such as <a class="link" href="functions.html#function_user"><code class="literal">USER()</code></a> or
            <a class="link" href="functions.html#function_version"><code class="literal">VERSION()</code></a>) has a coercibility
            of 3.
          </p></li><li class="listitem"><p>
            The collation of a literal has a coercibility of 4.
          </p></li><li class="listitem"><p>
            The collation of a numeric or temporal value has a
            coercibility of 5.
          </p></li><li class="listitem"><p>
            <code class="literal">NULL</code> or an expression that is derived
            from <code class="literal">NULL</code> has a coercibility of 6.
</p></li></ul>
</div>
<p>
        MySQL uses coercibility values with the following rules to
        resolve ambiguities:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            Use the collation with the lowest coercibility value.
          </p></li><li class="listitem"><p>
            If both sides have the same coercibility, then:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
                If both sides are Unicode, or both sides are not
                Unicode, it is an error.
              </p></li><li class="listitem"><p>
                If one of the sides has a Unicode character set, and
                another side has a non-Unicode character set, the side
                with Unicode character set wins, and automatic character
                set conversion is applied to the non-Unicode side. For
                example, the following statement does not return an
                error:
              </p><pre data-lang="sql" class="programlisting">
SELECT CONCAT(utf8_column, latin1_column) FROM t1;
</pre><p>
                It returns a result that has a character set of
                <code class="literal">utf8</code> and the same collation as
                <code class="literal">utf8_column</code>. Values of
                <code class="literal">latin1_column</code> are automatically
                converted to <code class="literal">utf8</code> before
                concatenating.
              </p></li><li class="listitem"><p>
                For an operation with operands from the same character
                set but that mix a <code class="literal">_bin</code> collation and
                a <code class="literal">_ci</code> or <code class="literal">_cs</code>
                collation, the <code class="literal">_bin</code> collation is
                used. This is similar to how operations that mix
                nonbinary and binary strings evaluate the operands as
                binary strings, except that it is for collations rather
                than data types.
</p></li></ul>
</div>
</li></ul>
</div>
<p>
        Although automatic conversion is not in the SQL standard, the
        standard does say that every character set is (in terms of
        supported characters) a <span class="quote">“<span class="quote">subset</span>”</span> of Unicode.
        Because it is a well-known principle that <span class="quote">“<span class="quote">what applies to
        a superset can apply to a subset,</span>”</span> we believe that a
        collation for Unicode can apply for comparisons with non-Unicode
        strings.
      </p><p>
        The following table illustrates some applications of the
        preceding rules.
</p>
<div class="informaltable">
<table summary="Comparisons and the collation used for each comparison."><col width="50%"><col width="50%"><thead><tr>
            <th scope="col">Comparison</th>
            <th scope="col">Collation Used</th>
          </tr></thead><tbody><tr>
            <td scope="row"><code class="literal">column1 = 'A'</code></td>
            <td>Use collation of <code class="literal">column1</code></td>
          </tr><tr>
            <td scope="row"><code class="literal">column1 = 'A' COLLATE x</code></td>
            <td>Use collation of <code class="literal">'A' COLLATE x</code></td>
          </tr><tr>
            <td scope="row"><code class="literal">column1 COLLATE x = 'A' COLLATE y</code></td>
            <td>Error</td>
</tr></tbody></table>
</div>
<p>
        To determine the coercibility of a string expression, use the
        <a class="link" href="functions.html#function_coercibility"><code class="literal">COERCIBILITY()</code></a> function (see
        <a class="xref" href="functions.html#information-functions" title="12.15 Information Functions">Section 12.15, “Information Functions”</a>):
      </p><pre data-lang="sql" class="programlisting">
mysql&gt; <strong class="userinput"><code>SELECT COERCIBILITY('A' COLLATE latin1_swedish_ci);</code></strong>
        -&gt; 0
mysql&gt; <strong class="userinput"><code>SELECT COERCIBILITY(VERSION());</code></strong>
        -&gt; 3
mysql&gt; <strong class="userinput"><code>SELECT COERCIBILITY('A');</code></strong>
        -&gt; 4
mysql&gt; <strong class="userinput"><code>SELECT COERCIBILITY(1000);</code></strong>
        -&gt; 5
</pre><p>
        For implicit conversion of a numeric or temporal value to a
        string, such as occurs for the argument <code class="literal">1</code> in
        the expression <a class="link" href="functions.html#function_concat"><code class="literal">CONCAT(1, 'abc')</code></a>,
        the result is a character (nonbinary) string that has a
        character set and collation determined by the
        <a class="link" href="server-administration.html#sysvar_character_set_connection"><code class="literal">character_set_connection</code></a> and
        <a class="link" href="server-administration.html#sysvar_collation_connection"><code class="literal">collation_connection</code></a> system
        variables. See <a class="xref" href="functions.html#type-conversion" title="12.2 Type Conversion in Expression Evaluation">Section 12.2, “Type Conversion in Expression Evaluation”</a>.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="charset-binary-collations"></a>10.8.5 The binary Collation Compared to _bin Collations</h3>

</div>

</div>

</div>
<a class="indexterm" name="idm140091697137600"></a><a class="indexterm" name="idm140091697136528"></a><a class="indexterm" name="idm140091697135040"></a><a class="indexterm" name="idm140091697133968"></a><p>
        This section describes how the <code class="literal">binary</code>
        collation for binary strings compares to <code class="literal">_bin</code>
        collations for nonbinary strings.
      </p><p>
        Binary strings (as stored using the
        <a class="link" href="data-types.html#binary-varbinary" title="11.4.2 The BINARY and VARBINARY Types"><code class="literal">BINARY</code></a>,
        <a class="link" href="data-types.html#binary-varbinary" title="11.4.2 The BINARY and VARBINARY Types"><code class="literal">VARBINARY</code></a>, and
        <a class="link" href="data-types.html#blob" title="11.4.3 The BLOB and TEXT Types"><code class="literal">BLOB</code></a> data types) have a character
        set and collation named <code class="literal">binary</code>. Binary
        strings are sequences of bytes and the numeric values of those
        bytes determine comparison and sort order.
      </p><p>
        Nonbinary strings (as stored using the
        <a class="link" href="data-types.html#char" title="11.4.1 The CHAR and VARCHAR Types"><code class="literal">CHAR</code></a>,
        <a class="link" href="data-types.html#char" title="11.4.1 The CHAR and VARCHAR Types"><code class="literal">VARCHAR</code></a>, and
        <a class="link" href="data-types.html#blob" title="11.4.3 The BLOB and TEXT Types"><code class="literal">TEXT</code></a> data types) have a character
        set and collation other than <code class="literal">binary</code>. A given
        nonbinary character set can have several collations, each of
        which defines a particular comparison and sort order for the
        characters in the set. One of these is the binary collation for
        the character set, indicated by a <code class="literal">_bin</code> suffix
        in the collation name. For example, the binary collations for
        <code class="literal">utf8</code> and <code class="literal">latin1</code> are named
        <code class="literal">utf8_bin</code> and <code class="literal">latin1_bin</code>,
        respectively. (<code class="literal">utf8mb4</code> is an exception that
        has two binary collations; see
        <a class="xref" href="charset.html#charset-unicode-sets" title="10.10.1 Unicode Character Sets">Section 10.10.1, “Unicode Character Sets”</a>.)
      </p><p>
        The <code class="literal">binary</code> collation differs from
        <code class="literal">_bin</code> collations in several respects,
        discussed in the following sections:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><a class="xref" href="charset.html#charset-binary-collations-comparison-units" title="The Unit for Comparison and Sorting">The Unit for Comparison and Sorting</a></p></li><li class="listitem"><p><a class="xref" href="charset.html#charset-binary-collations-charset-conversion" title="Character Set Conversion">Character Set Conversion</a></p></li><li class="listitem"><p><a class="xref" href="charset.html#charset-binary-collations-lettercase-conversion" title="Lettercase Conversion">Lettercase Conversion</a></p></li><li class="listitem"><p><a class="xref" href="charset.html#charset-binary-collations-trailing-space-comparisons" title="Trailing Space Handling in Comparisons">Trailing Space Handling in Comparisons</a></p></li><li class="listitem"><p><a class="xref" href="charset.html#charset-binary-collations-trailing-space-inserts-retrievals" title="Trailing Space Handling for Inserts and Retrievals">Trailing Space Handling for Inserts and Retrievals</a></p></li></ul>
</div>

<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h4 class="title"><a name="charset-binary-collations-comparison-units"></a>The Unit for Comparison and Sorting</h4>

</div>

</div>

</div>
<p>
          Binary strings are sequences of bytes. For the
          <code class="literal">binary</code> collation, comparison and sorting
          are based on numeric byte values. Nonbinary strings are
          sequences of characters, which might be multibyte. Collations
          for nonbinary strings define an ordering of the character
          values for comparison and sorting. For <code class="literal">_bin</code>
          collations, this ordering is based on numeric character code
          values, which is similar to ordering for binary strings except
          that character code values might be multibyte.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h4 class="title"><a name="charset-binary-collations-charset-conversion"></a>Character Set Conversion</h4>

</div>

</div>

</div>
<p>
          A nonbinary string has a character set and is automatically
          converted to another character set in many cases, even when
          the string has a <code class="literal">_bin</code> collation:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              When assigning column values to another column that has a
              different character set:
            </p><pre data-lang="sql" class="programlisting">
UPDATE t1 SET utf8_bin_column=latin1_column;
INSERT INTO t1 (latin1_column) SELECT utf8_bin_column FROM t2;
</pre></li><li class="listitem"><p>
              When assigning column values for
              <a class="link" href="sql-syntax.html#insert" title="13.2.6 INSERT Syntax"><code class="literal">INSERT</code></a> or
              <a class="link" href="sql-syntax.html#update" title="13.2.12 UPDATE Syntax"><code class="literal">UPDATE</code></a> using a string
              literal:
            </p><pre data-lang="sql" class="programlisting">
SET NAMES latin1;
INSERT INTO t1 (utf8_bin_column) VALUES ('string-in-latin1');
</pre></li><li class="listitem"><p>
              When sending results from the server to a client:
            </p><pre data-lang="sql" class="programlisting">
SET NAMES latin1;
SELECT utf8_bin_column FROM t2;
</pre></li></ul>
</div>
<p>
          For binary string columns, no conversion occurs. For cases
          similar to those preceding, the string value is copied
          byte-wise.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h4 class="title"><a name="charset-binary-collations-lettercase-conversion"></a>Lettercase Conversion</h4>

</div>

</div>

</div>
<p>
          Collations for nonbinary character sets provide information
          about lettercase of characters, so characters in a nonbinary
          string can be converted from one lettercase to another, even
          for <code class="literal">_bin</code> collations that ignore lettercase
          for ordering:
        </p><pre data-lang="sql" class="programlisting">
mysql&gt; <strong class="userinput"><code>SET NAMES utf8mb4 COLLATE utf8mb4_bin;</code></strong>
mysql&gt; <strong class="userinput"><code>SELECT LOWER('aA'), UPPER('zZ');</code></strong>
+-------------+-------------+
| LOWER('aA') | UPPER('zZ') |
+-------------+-------------+
| aa          | ZZ          |
+-------------+-------------+
</pre><p>
          The concept of lettercase does not apply to bytes in a binary
          string. To perform lettercase conversion, the string must be
          converted to a nonbinary string:
        </p><pre data-lang="sql" class="programlisting">
mysql&gt; <strong class="userinput"><code>SET NAMES binary;</code></strong>
mysql&gt; <strong class="userinput"><code>SELECT LOWER('aA'), LOWER(CONVERT('aA' USING utf8mb4));</code></strong>
+-------------+------------------------------------+
| LOWER('aA') | LOWER(CONVERT('aA' USING utf8mb4)) |
+-------------+------------------------------------+
| aA          | aa                                 |
+-------------+------------------------------------+
</pre>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h4 class="title"><a name="charset-binary-collations-trailing-space-comparisons"></a>Trailing Space Handling in Comparisons</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140091697082352"></a><a class="indexterm" name="idm140091697080864"></a><a class="indexterm" name="idm140091697079792"></a><a class="indexterm" name="idm140091697078304"></a><p>
          Many MySQL collations have a pad attribute of <code class="literal">PAD
          SPACE</code>. The Unicode collations based on UCA 9.0.0 and
          higher have a pad attribute of <code class="literal">NO PAD</code>; see
          <a class="xref" href="charset.html#charset-unicode-sets" title="10.10.1 Unicode Character Sets">Section 10.10.1, “Unicode Character Sets”</a>.
        </p><p>
          The pad attribute determines how trailing spaces are treated
          for comparison of nonbinary strings (<code class="literal">CHAR</code>,
          <code class="literal">VARCHAR</code>, and <code class="literal">TEXT</code>
          values):
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              For <code class="literal">PAD SPACE</code> collations, trailing
              spaces are insignificant in comparisons; strings are
              compared without regard to any trailing spaces.
            </p></li><li class="listitem"><p>
              <code class="literal">NO PAD</code> collations treat spaces at the
              end of strings like any other character.
</p></li></ul>
</div>
<p>
          The differing behaviors can be demonstrated using the two
          <code class="literal">utf8mb4</code> binary collations, one of which is
          <code class="literal">PAD SPACE</code>, the other of which is
          <code class="literal">NO PAD</code>. The example also shows how to use
          the <code class="literal">INFORMATION_SCHEMA</code>
          <a class="link" href="information-schema.html#collations-table" title="25.4 The INFORMATION_SCHEMA COLLATIONS Table"><code class="literal">COLLATIONS</code></a> table to determine the
          pad attribute for collations.
        </p><pre data-lang="sql" class="programlisting">
mysql&gt; <strong class="userinput"><code>SELECT COLLATION_NAME, PAD_ATTRIBUTE</code></strong>
       <strong class="userinput"><code>FROM INFORMATION_SCHEMA.COLLATIONS</code></strong>
       <strong class="userinput"><code>WHERE COLLATION_NAME LIKE 'utf8mb4%bin';</code></strong>
+------------------+---------------+
| COLLATION_NAME   | PAD_ATTRIBUTE |
+------------------+---------------+
| utf8mb4_bin      | PAD SPACE     |
| utf8mb4_0900_bin | NO PAD        |
+------------------+---------------+
mysql&gt; <strong class="userinput"><code>SET NAMES utf8mb4 COLLATE utf8mb4_bin;</code></strong>
mysql&gt; <strong class="userinput"><code>SELECT 'a ' = 'a';</code></strong>
+------------+
| 'a ' = 'a' |
+------------+
|          1 |
+------------+
mysql&gt; <strong class="userinput"><code>SET NAMES utf8mb4 COLLATE utf8mb4_0900_bin;</code></strong>
mysql&gt; <strong class="userinput"><code>SELECT 'a ' = 'a';</code></strong>
+------------+
| 'a ' = 'a' |
+------------+
|          0 |
+------------+
</pre><p>
          For binary strings, all characters are significant in
          comparisons, including trailing spaces:
        </p><pre data-lang="sql" class="programlisting">
mysql&gt; <strong class="userinput"><code>SET NAMES binary;</code></strong>
mysql&gt; <strong class="userinput"><code>SELECT 'a ' = 'a';</code></strong>
+------------+
| 'a ' = 'a' |
+------------+
|          0 |
+------------+
</pre>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h4 class="title"><a name="charset-binary-collations-trailing-space-inserts-retrievals"></a>Trailing Space Handling for Inserts and Retrievals</h4>

</div>

</div>

</div>
<p>
          <code class="literal">CHAR(<em class="replaceable"><code>N</code></em>)</code> columns
          store nonbinary strings. For inserts, values shorter than
          <em class="replaceable"><code>N</code></em> characters are extended with
          spaces. For retrievals, trailing spaces are removed.
        </p><p>
          <code class="literal">BINARY(<em class="replaceable"><code>N</code></em>)</code>
          columns store binary strings. For inserts, values shorter than
          <em class="replaceable"><code>N</code></em> bytes are extended with
          <code class="literal">0x00</code> bytes. For retrievals, nothing is
          removed; a value of the declared length is always returned.
        </p><pre data-lang="sql" class="programlisting">
mysql&gt; <strong class="userinput"><code>CREATE TABLE t1 (</code></strong>
         <strong class="userinput"><code>a CHAR(10) CHARACTER SET utf8 COLLATE utf8_bin,</code></strong>
         <strong class="userinput"><code>b BINARY(10)</code></strong>
       <strong class="userinput"><code>);</code></strong>
mysql&gt; <strong class="userinput"><code>INSERT INTO t1 VALUES ('a','a');</code></strong>
mysql&gt; <strong class="userinput"><code>SELECT HEX(a), HEX(b) FROM t1;</code></strong>
+--------+----------------------+
| HEX(a) | HEX(b)               |
+--------+----------------------+
| 61     | 61000000000000000000 |
+--------+----------------------+
</pre>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="charset-collation-effect"></a>10.8.6 Examples of the Effect of Collation</h3>

</div>

</div>

</div>
<p>
        <span class="bold"><strong>Example 1: Sorting German
        Umlauts</strong></span>
      </p><p>
        Suppose that column <code class="literal">X</code> in table
        <code class="literal">T</code> has these <code class="literal">latin1</code> column
        values:
      </p><pre data-lang="none" class="programlisting">
Muffler
Müller
MX Systems
MySQL
</pre><p>
        Suppose also that the column values are retrieved using the
        following statement:
      </p><pre data-lang="sql" class="programlisting">
SELECT X FROM T ORDER BY X COLLATE <em class="replaceable"><code>collation_name</code></em>;
</pre><p>
        The following table shows the resulting order of the values if
        we use <code class="literal">ORDER BY</code> with different collations.
</p>
<div class="informaltable">
<table summary="An example of the effect of collation, as described in the preceding text. The table shows the resulting order of values for three collations (latin1_swedish_ci, latin1_german1_ci, latin1_german2_ci) when using ORDER BY."><col width="30%"><col width="30%"><col width="30%"><thead><tr>
            <th scope="col"><code class="literal">latin1_swedish_ci</code></th>
            <th scope="col"><code class="literal">latin1_german1_ci</code></th>
            <th scope="col"><code class="literal">latin1_german2_ci</code></th>
          </tr></thead><tbody><tr>
            <td scope="row">Muffler</td>
            <td>Muffler</td>
            <td>Müller</td>
          </tr><tr>
            <td scope="row">MX Systems</td>
            <td>Müller</td>
            <td>Muffler</td>
          </tr><tr>
            <td scope="row">Müller</td>
            <td>MX Systems</td>
            <td>MX Systems</td>
          </tr><tr>
            <td scope="row">MySQL</td>
            <td>MySQL</td>
            <td>MySQL</td>
</tr></tbody></table>
</div>
<p>
        The character that causes the different sort orders in this
        example is the U with two dots over it
        (<code class="literal">ü</code>), which the Germans call
        <span class="quote">“<span class="quote">U-umlaut.</span>”</span>
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            The first column shows the result of the
            <a class="link" href="sql-syntax.html#select" title="13.2.10 SELECT Syntax"><code class="literal">SELECT</code></a> using the
            Swedish/Finnish collating rule, which says that U-umlaut
            sorts with Y.
          </p></li><li class="listitem"><p>
            The second column shows the result of the
            <a class="link" href="sql-syntax.html#select" title="13.2.10 SELECT Syntax"><code class="literal">SELECT</code></a> using the German DIN-1
            rule, which says that U-umlaut sorts with U.
          </p></li><li class="listitem"><p>
            The third column shows the result of the
            <a class="link" href="sql-syntax.html#select" title="13.2.10 SELECT Syntax"><code class="literal">SELECT</code></a> using the German DIN-2
            rule, which says that U-umlaut sorts with UE.
</p></li></ul>
</div>
<p>
        <span class="bold"><strong>Example 2: Searching for German
        Umlauts</strong></span>
      </p><p>
        Suppose that you have three tables that differ only by the
        character set and collation used:
      </p><pre data-lang="sql" class="programlisting">
mysql&gt; <strong class="userinput"><code>SET NAMES utf8;</code></strong>
mysql&gt; <strong class="userinput"><code>CREATE TABLE german1 (</code></strong>
       <strong class="userinput"><code>  c CHAR(10)</code></strong>
       <strong class="userinput"><code>) CHARACTER SET latin1 COLLATE latin1_german1_ci;</code></strong>
mysql&gt; <strong class="userinput"><code>CREATE TABLE german2 (</code></strong>
       <strong class="userinput"><code>  c CHAR(10)</code></strong>
       <strong class="userinput"><code>) CHARACTER SET latin1 COLLATE latin1_german2_ci;</code></strong>
mysql&gt; <strong class="userinput"><code>CREATE TABLE germanutf8 (</code></strong>
       <strong class="userinput"><code>  c CHAR(10)</code></strong>
       <strong class="userinput"><code>) CHARACTER SET utf8 COLLATE utf8_unicode_ci;</code></strong>
</pre><p>
        Each table contains two records:
      </p><pre data-lang="sql" class="programlisting">
mysql&gt; <strong class="userinput"><code>INSERT INTO german1 VALUES ('Bar'), ('Bär');</code></strong>
mysql&gt; <strong class="userinput"><code>INSERT INTO german2 VALUES ('Bar'), ('Bär');</code></strong>
mysql&gt; <strong class="userinput"><code>INSERT INTO germanutf8 VALUES ('Bar'), ('Bär');</code></strong>
</pre><p>
        Two of the above collations have an <code class="literal">A = Ä</code>
        equality, and one has no such equality
        (<code class="literal">latin1_german2_ci</code>). For that reason, you'll
        get these results in comparisons:
      </p><pre data-lang="sql" class="programlisting">
mysql&gt; <strong class="userinput"><code>SELECT * FROM german1 WHERE c = 'Bär';</code></strong>
+------+
| c    |
+------+
| Bar  |
| Bär  |
+------+
mysql&gt; <strong class="userinput"><code>SELECT * FROM german2 WHERE c = 'Bär';</code></strong>
+------+
| c    |
+------+
| Bär  |
+------+
mysql&gt; <strong class="userinput"><code>SELECT * FROM germanutf8 WHERE c = 'Bär';</code></strong>
+------+
| c    |
+------+
| Bar  |
| Bär  |
+------+
</pre><p>
        This is not a bug but rather a consequence of the sorting
        properties of <code class="literal">latin1_german1_ci</code> and
        <code class="literal">utf8_unicode_ci</code> (the sorting shown is done
        according to the German DIN 5007 standard).
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="charset-collation-information-schema"></a>10.8.7 Using Collation in INFORMATION_SCHEMA Searches</h3>

</div>

</div>

</div>
<a class="indexterm" name="idm140091696980352"></a><a class="indexterm" name="idm140091696978864"></a><p>
        String columns in <code class="literal">INFORMATION_SCHEMA</code> tables
        have a collation of <code class="literal">utf8_general_ci</code>, which is
        case insensitive. However, for values that correspond to objects
        that are represented in the file system, such as databases and
        tables, searches in <code class="literal">INFORMATION_SCHEMA</code> string
        columns can be case-sensitive or insensitive, depending on the
        characteristics of the underlying file system and the
        <a class="link" href="server-administration.html#sysvar_lower_case_table_names"><code class="literal">lower_case_table_names</code></a> system
        variable setting. For example, searches may be case-sensitive if
        the file system is case-sensitive. This section describes this
        behavior and how to modify it if necessary.
      </p><p>
        Suppose that a query searches the
        <code class="literal">SCHEMATA.SCHEMA_NAME</code> column for the
        <code class="literal">test</code> database. On Linux, file systems are
        case-sensitive, so comparisons of
        <code class="literal">SCHEMATA.SCHEMA_NAME</code> with
        <code class="literal">'test'</code> match, but comparisons with
        <code class="literal">'TEST'</code> do not:
      </p><pre data-lang="sql" class="programlisting">
mysql&gt; <strong class="userinput"><code>SELECT SCHEMA_NAME FROM INFORMATION_SCHEMA.SCHEMATA</code></strong>
       <strong class="userinput"><code>WHERE SCHEMA_NAME = 'test';</code></strong>
+-------------+
| SCHEMA_NAME |
+-------------+
| test        |
+-------------+

mysql&gt; <strong class="userinput"><code>SELECT SCHEMA_NAME FROM INFORMATION_SCHEMA.SCHEMATA</code></strong>
       <strong class="userinput"><code>WHERE SCHEMA_NAME = 'TEST';</code></strong>
Empty set (0.00 sec)
</pre><p>
        These results occur with the
        <a class="link" href="server-administration.html#sysvar_lower_case_table_names"><code class="literal">lower_case_table_names</code></a> system
        variable set to 0. A
        <a class="link" href="server-administration.html#sysvar_lower_case_table_names"><code class="literal">lower_case_table_names</code></a> setting
        of 1 or 2 causes the second query to return the same (nonempty)
        result as the first query.
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Note
</div>
<p>
          It is prohibited to start the server with a
          <a class="link" href="server-administration.html#sysvar_lower_case_table_names"><code class="literal">lower_case_table_names</code></a>
          setting that is different from the setting used when the
          server was initialized.
</p>
</div>
<p>
        On Windows or macOS, file systems are not case-sensitive, so
        comparisons match both <code class="literal">'test'</code> and
        <code class="literal">'TEST'</code>:
      </p><pre data-lang="sql" class="programlisting">
mysql&gt; <strong class="userinput"><code>SELECT SCHEMA_NAME FROM INFORMATION_SCHEMA.SCHEMATA</code></strong>
       <strong class="userinput"><code>WHERE SCHEMA_NAME = 'test';</code></strong>
+-------------+
| SCHEMA_NAME |
+-------------+
| test        |
+-------------+

mysql&gt; <strong class="userinput"><code>SELECT SCHEMA_NAME FROM INFORMATION_SCHEMA.SCHEMATA</code></strong>
       <strong class="userinput"><code>WHERE SCHEMA_NAME = 'TEST';</code></strong>
+-------------+
| SCHEMA_NAME |
+-------------+
| TEST        |
+-------------+
</pre><p>
        The value of
        <a class="link" href="server-administration.html#sysvar_lower_case_table_names"><code class="literal">lower_case_table_names</code></a> makes no
        difference in this context.
      </p><p>
        The preceding behavior occurs because the
        <code class="literal">utf8_general_ci</code> collation is not used for
        <code class="literal">INFORMATION_SCHEMA</code> queries when searching for
        values that correspond to objects represented in the file
        system.
      </p><p>
        If the result of a string operation on an
        <code class="literal">INFORMATION_SCHEMA</code> column differs from
        expectations, a workaround is to use an explicit
        <code class="literal">COLLATE</code> clause to force a suitable collation
        (see <a class="xref" href="charset.html#charset-collate" title="10.8.1 Using COLLATE in SQL Statements">Section 10.8.1, “Using COLLATE in SQL Statements”</a>). For example, to perform
        a case-insensitive search, use <code class="literal">COLLATE</code> with
        the <code class="literal">INFORMATION_SCHEMA</code> column name:
      </p><pre data-lang="sql" class="programlisting">
mysql&gt; <strong class="userinput"><code>SELECT SCHEMA_NAME FROM INFORMATION_SCHEMA.SCHEMATA</code></strong>
       <strong class="userinput"><code>WHERE SCHEMA_NAME COLLATE utf8_general_ci = 'test';</code></strong>
+-------------+
| SCHEMA_NAME |
+-------------+
| test        |
+-------------+

mysql&gt; <strong class="userinput"><code>SELECT SCHEMA_NAME FROM INFORMATION_SCHEMA.SCHEMATA</code></strong>
       <strong class="userinput"><code>WHERE SCHEMA_NAME COLLATE utf8_general_ci = 'TEST';</code></strong>
+-------------+
| SCHEMA_NAME |
+-------------+
| test        |
+-------------+
</pre><p>
        You can also use the <a class="link" href="functions.html#function_upper"><code class="literal">UPPER()</code></a> or
        <a class="link" href="functions.html#function_lower"><code class="literal">LOWER()</code></a> function:
      </p><pre data-lang="sql" class="programlisting">
WHERE UPPER(SCHEMA_NAME) = 'TEST'
WHERE LOWER(SCHEMA_NAME) = 'test'
</pre><p>
        Although a case-insensitive comparison can be performed even on
        platforms with case-sensitive file systems, as just shown, it is
        not necessarily always the right thing to do. On such platforms,
        it is possible to have multiple objects with names that differ
        only in lettercase. For example, tables named
        <code class="literal">city</code>, <code class="literal">CITY</code>, and
        <code class="literal">City</code> can all exist simultaneously. Consider
        whether a search should match all such names or just one and
        write queries accordingly. The first of the following
        comparisons (with <code class="literal">utf8_bin</code>) is case
        sensitive; the others are not:
      </p><pre data-lang="sql" class="programlisting">
WHERE TABLE_NAME COLLATE utf8_bin = 'City'
WHERE TABLE_NAME COLLATE utf8_general_ci = 'city'
WHERE UPPER(TABLE_NAME) = 'CITY'
WHERE LOWER(TABLE_NAME) = 'city'
</pre><p>
        Searches in <code class="literal">INFORMATION_SCHEMA</code> string columns
        for values that refer to <code class="literal">INFORMATION_SCHEMA</code>
        itself do use the <code class="literal">utf8_general_ci</code> collation
        because <code class="literal">INFORMATION_SCHEMA</code> is a
        <span class="quote">“<span class="quote">virtual</span>”</span> database not represented in the file
        system. For example, comparisons with
        <code class="literal">SCHEMATA.SCHEMA_NAME</code> match
        <code class="literal">'information_schema'</code> or
        <code class="literal">'INFORMATION_SCHEMA'</code> regardless of platform:
      </p><pre data-lang="sql" class="programlisting">
mysql&gt; <strong class="userinput"><code>SELECT SCHEMA_NAME FROM INFORMATION_SCHEMA.SCHEMATA</code></strong>
       <strong class="userinput"><code>WHERE SCHEMA_NAME = 'information_schema';</code></strong>
+--------------------+
| SCHEMA_NAME        |
+--------------------+
| information_schema |
+--------------------+

mysql&gt; <strong class="userinput"><code>SELECT SCHEMA_NAME FROM INFORMATION_SCHEMA.SCHEMATA</code></strong>
       <strong class="userinput"><code>WHERE SCHEMA_NAME = 'INFORMATION_SCHEMA';</code></strong>
+--------------------+
| SCHEMA_NAME        |
+--------------------+
| information_schema |
+--------------------+
</pre>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both"><a name="charset-unicode"></a>10.9 Unicode Support</h2>

</div>

</div>

</div>
<div class="toc">
<dl class="toc"><dt><span class="section"><a href="charset.html#charset-unicode-utf8mb4">10.9.1 The utf8mb4 Character Set (4-Byte UTF-8 Unicode Encoding)</a></span></dt><dt><span class="section"><a href="charset.html#charset-unicode-utf8mb3">10.9.2 The utf8mb3 Character Set (3-Byte UTF-8 Unicode Encoding)</a></span></dt><dt><span class="section"><a href="charset.html#charset-unicode-utf8">10.9.3 The utf8 Character Set (Alias for utf8mb3)</a></span></dt><dt><span class="section"><a href="charset.html#charset-unicode-ucs2">10.9.4 The ucs2 Character Set (UCS-2 Unicode Encoding)</a></span></dt><dt><span class="section"><a href="charset.html#charset-unicode-utf16">10.9.5 The utf16 Character Set (UTF-16 Unicode Encoding)</a></span></dt><dt><span class="section"><a href="charset.html#charset-unicode-utf16le">10.9.6 The utf16le Character Set (UTF-16LE Unicode Encoding)</a></span></dt><dt><span class="section"><a href="charset.html#charset-unicode-utf32">10.9.7 The utf32 Character Set (UTF-32 Unicode Encoding)</a></span></dt><dt><span class="section"><a href="charset.html#charset-unicode-conversion">10.9.8 Converting Between 3-Byte and 4-Byte Unicode Character Sets</a></span></dt></dl>
</div>
<p>
      The Unicode Standard includes characters from the Basic
      Multilingual Plane (BMP) and supplementary characters that lie
      outside the BMP. This section describes support for Unicode in
      MySQL. For information about the Unicode Standard itself, visit
      the <a class="ulink" href="http://www.unicode.org/" target="_top">Unicode Consortium
      website</a>.
    </p><p>
      BMP characters have these characteristics:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          Their code point values are between 0 and 65535 (or
          <code class="literal">U+0000</code> and <code class="literal">U+FFFF</code>).
        </p></li><li class="listitem"><p>
          They can be encoded in a variable-length encoding using 8, 16,
          or 24 bits (1 to 3 bytes).
        </p></li><li class="listitem"><p>
          They can be encoded in a fixed-length encoding using 16 bits
          (2 bytes).
        </p></li><li class="listitem"><p>
          They are sufficient for almost all characters in major
          languages.
</p></li></ul>
</div>
<p>
      Supplementary characters lie outside the BMP:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          Their code point values are between <code class="literal">U+10000</code>
          and <code class="literal">U+10FFFF</code>).
        </p></li><li class="listitem"><p>
          Unicode support for supplementary characters requires
          character sets that have a range outside BMP characters and
          therefore take more space than BMP characters (up to 4 bytes
          per character).
</p></li></ul>
</div>
<p>
      The UTF-8 (Unicode Transformation Format with 8-bit units) method
      for encoding Unicode data is implemented according to RFC 3629,
      which describes encoding sequences that take from one to four
      bytes. The idea of UTF-8 is that various Unicode characters are
      encoded using byte sequences of different lengths:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          Basic Latin letters, digits, and punctuation signs use one
          byte.
        </p></li><li class="listitem"><p>
          Most European and Middle East script letters fit into a 2-byte
          sequence: extended Latin letters (with tilde, macron, acute,
          grave and other accents), Cyrillic, Greek, Armenian, Hebrew,
          Arabic, Syriac, and others.
        </p></li><li class="listitem"><p>
          Korean, Chinese, and Japanese ideographs use 3-byte or 4-byte
          sequences.
</p></li></ul>
</div>
<p>
      MySQL supports these Unicode character sets:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          <code class="literal">utf8mb4</code>: A UTF-8 encoding of the Unicode
          character set using one to four bytes per character.
        </p></li><li class="listitem"><p>
          <code class="literal">utf8mb3</code>: A UTF-8 encoding of the Unicode
          character set using one to three bytes per character.
        </p></li><li class="listitem"><p>
          <code class="literal">utf8</code>: An alias for
          <code class="literal">utf8mb3</code>.
        </p></li><li class="listitem"><p>
          <code class="literal">ucs2</code>: The UCS-2 encoding of the Unicode
          character set using two bytes per character.
        </p></li><li class="listitem"><p>
          <code class="literal">utf16</code>: The UTF-16 encoding for the Unicode
          character set using two or four bytes per character. Like
          <code class="literal">ucs2</code> but with an extension for
          supplementary characters.
        </p></li><li class="listitem"><p>
          <code class="literal">utf16le</code>: The UTF-16LE encoding for the
          Unicode character set. Like <code class="literal">utf16</code> but
          little-endian rather than big-endian.
        </p></li><li class="listitem"><p>
          <code class="literal">utf32</code>: The UTF-32 encoding for the Unicode
          character set using four bytes per character.
</p></li></ul>
</div>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<div class="admon-title">
Note
</div>
<p>
        The <code class="literal">utf8mb3</code> character set is deprecated and
        will be removed in a future MySQL release. Please use
        <code class="literal">utf8mb4</code> instead. Although
        <code class="literal">utf8</code> is currently an alias for
        <code class="literal">utf8mb3</code>, at some point
        <code class="literal">utf8</code> will become a reference to
        <code class="literal">utf8mb4</code>. To avoid ambiguity about the meaning
        of <code class="literal">utf8</code>, consider specifying
        <code class="literal">utf8mb4</code> explicitly for character set
        references instead of <code class="literal">utf8</code>.
</p>
</div>
<p>
      <a class="xref" href="charset.html#charset-unicode-charset-characteristics" title="Table 10.2 Unicode Character Set General Characteristics">Table 10.2, “Unicode Character Set General Characteristics”</a>,
      summarizes the general characteristics of Unicode character sets
      supported by MySQL.
</p>
<div class="table">
<a name="charset-unicode-charset-characteristics"></a><p class="title"><b>Table 10.2 Unicode Character Set General Characteristics</b></p>
<div class="table-contents">
<table summary="General characteristics of Unicode character sets."><col width="20%"><col width="40%"><col width="40%"><thead><tr>
          <th scope="col">Character Set</th>
          <th scope="col">Supported Characters</th>
          <th scope="col">Required Storage Per Character</th>
        </tr></thead><tbody><tr>
          <td scope="row"><code class="literal">utf8mb3</code>, <code class="literal">utf8</code></td>
          <td>BMP only</td>
          <td>1, 2, or 3 bytes</td>
        </tr><tr>
          <td scope="row"><code class="literal">ucs2</code></td>
          <td>BMP only</td>
          <td>2 bytes</td>
        </tr><tr>
          <td scope="row"><code class="literal">utf8mb4</code></td>
          <td>BMP and supplementary</td>
          <td>1, 2, 3, or 4 bytes</td>
        </tr><tr>
          <td scope="row"><code class="literal">utf16</code></td>
          <td>BMP and supplementary</td>
          <td>2 or 4 bytes</td>
        </tr><tr>
          <td scope="row"><code class="literal">utf16le</code></td>
          <td>BMP and supplementary</td>
          <td>2 or 4 bytes</td>
        </tr><tr>
          <td scope="row"><code class="literal">utf32</code></td>
          <td>BMP and supplementary</td>
          <td>4 bytes</td>
</tr></tbody></table>
</div>

</div>
<br class="table-break"><p>
      Characters outside the BMP compare as REPLACEMENT CHARACTER and
      convert to <code class="literal">'?'</code> when converted to a Unicode
      character set that supports only BMP characters
      (<code class="literal">utf8mb3</code> or <code class="literal">ucs2</code>).
    </p><p>
      If you use character sets that support supplementary characters
      and thus are <span class="quote">“<span class="quote">wider</span>”</span> than the BMP-only
      <code class="literal">utf8mb3</code> and <code class="literal">ucs2</code> character
      sets, there are potential incompatibility issues for your
      applications; see <a class="xref" href="charset.html#charset-unicode-conversion" title="10.9.8 Converting Between 3-Byte and 4-Byte Unicode Character Sets">Section 10.9.8, “Converting Between 3-Byte and 4-Byte Unicode Character Sets”</a>.
      That section also describes how to convert tables from the
      (3-byte) <code class="literal">utf8mb3</code> to the (4-byte)
      <code class="literal">utf8mb4</code>, and what constraints may apply in
      doing so.
    </p><p>
      A similar set of collations is available for most Unicode
      character sets. For example, each has a Danish collation, the
      names of which are <code class="literal">utf8mb4_danish_ci</code>,
      <code class="literal">utf8mb3_danish_ci</code>,
      <code class="literal">utf8_danish_ci</code>,
      <code class="literal">ucs2_danish_ci</code>,
      <code class="literal">utf16_danish_ci</code>, and
      <code class="literal">utf32_danish_ci</code>. The exception is
      <code class="literal">utf16le</code>, which has only two collations. For
      information about Unicode collations and their differentiating
      properties, including collation properties for supplementary
      characters, see <a class="xref" href="charset.html#charset-unicode-sets" title="10.10.1 Unicode Character Sets">Section 10.10.1, “Unicode Character Sets”</a>.
    </p><p>
      The MySQL implementation of UCS-2, UTF-16, and UTF-32 stores
      characters in big-endian byte order and does not use a byte order
      mark (BOM) at the beginning of values. Other database systems
      might use little-endian byte order or a BOM. In such cases,
      conversion of values will need to be performed when transferring
      data between those systems and MySQL. The implementation of
      UTF-16LE is little-endian.
    </p><p>
      MySQL uses no BOM for UTF-8 values.
    </p><p>
      Client applications that communicate with the server using Unicode
      should set the client character set accordingly (for example, by
      issuing a <code class="literal">SET NAMES 'utf8mb4'</code> statement). Some
      character sets cannot be used as the client character set.
      Attempting to use them with <a class="link" href="sql-syntax.html#set-names" title="13.7.5.3 SET NAMES Syntax"><code class="literal">SET
      NAMES</code></a> or <a class="link" href="sql-syntax.html#set-character-set" title="13.7.5.2 SET CHARACTER SET Syntax"><code class="literal">SET CHARACTER
      SET</code></a> produces an error. See
      <a class="xref" href="charset.html#charset-connection-impermissible-client-charset" title="Impermissible Client Character Sets">Impermissible Client Character Sets</a>.
    </p><p>
      The following sections provide additional detail on the Unicode
      character sets in MySQL.
</p>
<div class="section">

<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="charset-unicode-utf8mb4"></a>10.9.1 The utf8mb4 Character Set (4-Byte UTF-8 Unicode Encoding)</h3>
</div>
</div>
</div>
<a class="indexterm" name="idm140091696828848"></a><p>
        The <code class="literal">utfmb4</code> character set has these
        characteristics:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            Supports BMP and supplementary characters.
          </p></li><li class="listitem"><p>
            Requires a maximum of four bytes per multibyte character.
</p></li></ul>
</div>
<p>
        <code class="literal">utf8mb4</code> contrasts with the
        <code class="literal">utf8mb3</code> character set, which supports only
        BMP characters and uses a maximum of three bytes per character:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            For a BMP character, <code class="literal">utf8mb4</code> and
            <code class="literal">utf8mb3</code> have identical storage
            characteristics: same code values, same encoding, same
            length.
          </p></li><li class="listitem"><p>
            For a supplementary character, <code class="literal">utf8mb4</code>
            requires four bytes to store it, whereas
            <code class="literal">utf8mb3</code> cannot store the character at
            all. When converting <code class="literal">utf8mb3</code> columns to
            <code class="literal">utf8mb4</code>, you need not worry about
            converting supplementary characters because there will be
            none.
</p></li></ul>
</div>
<p>
        <code class="literal">utf8mb4</code> is a superset of
        <code class="literal">utf8mb3</code>, so for an operation such as the
        following concatenation, the result has character set
        <code class="literal">utf8mb4</code> and the collation of
        <code class="literal">utf8mb4_col</code>:
      </p><pre data-lang="sql" class="programlisting">
SELECT CONCAT(utf8mb3_col, utf8mb4_col);
</pre><p>
        Similarly, the following comparison in the
        <code class="literal">WHERE</code> clause works according to the collation
        of <code class="literal">utf8mb4_col</code>:
      </p><pre data-lang="sql" class="programlisting">
SELECT * FROM utf8mb3_tbl, utf8mb4_tbl
WHERE utf8mb3_tbl.utf8mb3_col = utf8mb4_tbl.utf8mb4_col;
</pre><p>
        For information about data type storage as it relates to
        multibyte character sets, see
        <a class="xref" href="data-types.html#data-types-storage-reqs-strings" title="String Type Storage Requirements">String Type Storage Requirements</a>.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="charset-unicode-utf8mb3"></a>10.9.2 The utf8mb3 Character Set (3-Byte UTF-8 Unicode Encoding)</h3>

</div>

</div>

</div>
<a class="indexterm" name="idm140091696805856"></a><a class="indexterm" name="idm140091696804816"></a><a class="indexterm" name="idm140091696803328"></a><p>
        The <code class="literal">utf8mb3</code> character set has these
        characteristics:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            Supports BMP characters only (no support for supplementary
            characters)
          </p></li><li class="listitem"><p>
            Requires a maximum of three bytes per multibyte character.
</p></li></ul>
</div>
<p>
        Applications that use UTF-8 data but require supplementary
        character support should use <code class="literal">utf8mb4</code> rather
        than <code class="literal">utf8mb3</code> (see
        <a class="xref" href="charset.html#charset-unicode-utf8mb4" title="10.9.1 The utf8mb4 Character Set (4-Byte UTF-8 Unicode Encoding)">Section 10.9.1, “The utf8mb4 Character Set (4-Byte UTF-8 Unicode Encoding)”</a>).
      </p><a class="indexterm" name="idm140091696795808"></a><a class="indexterm" name="idm140091696794720"></a><p>
        Exactly the same set of characters is available in
        <code class="literal">utf8mb3</code> and <code class="literal">ucs2</code>. That is,
        they have the same
        <a class="link" href="glossary.html#glos_repertoire" title="repertoire">repertoire</a>.
      </p><p>
        <code class="literal">utf8</code> is an alias for
        <code class="literal">utf8mb3</code>; the character limit is implicit,
        rather than explicit in the name.
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Note
</div>
<p>
          The <code class="literal">utf8mb3</code> character set is deprecated and
          will be removed in a future MySQL release. Please use
          <code class="literal">utf8mb4</code> instead. Although
          <code class="literal">utf8</code> is currently an alias for
          <code class="literal">utf8mb3</code>, at some point
          <code class="literal">utf8</code> will become a reference to
          <code class="literal">utf8mb4</code>. To avoid ambiguity about the
          meaning of <code class="literal">utf8</code>, consider specifying
          <code class="literal">utf8mb4</code> explicitly for character set
          references instead of <code class="literal">utf8</code>.
</p>
</div>
<p>
        <code class="literal">utf8mb3</code> can be used in <code class="literal">CHARACTER
        SET</code> clauses, and
        <code class="literal">utf8mb3_<em class="replaceable"><code>collation_substring</code></em></code>
        in <code class="literal">COLLATE</code> clauses, where
        <em class="replaceable"><code>collation_substring</code></em> is
        <code class="literal">bin</code>, <code class="literal">czech_ci</code>,
        <code class="literal">danish_ci</code>, <code class="literal">esperanto_ci</code>,
        <code class="literal">estonian_ci</code>, and so forth. For example:
      </p><pre data-lang="sql" class="programlisting">
CREATE TABLE t (s1 CHAR(1) CHARACTER SET utf8mb3;
SELECT * FROM t WHERE s1 COLLATE utf8mb3_general_ci = 'x';
DECLARE x VARCHAR(5) CHARACTER SET utf8mb3 COLLATE utf8mb3_danish_ci;
SELECT CAST('a' AS CHAR CHARACTER SET utf8) COLLATE utf8_czech_ci;
</pre><p>
        MySQL immediately converts instances of
        <code class="literal">utf8mb3</code> in statements to
        <code class="literal">utf8</code>, so in statements such as <code class="literal">SHOW
        CREATE TABLE</code> or <code class="literal">SELECT CHARACTER_SET_NAME
        FROM INFORMATION_SCHEMA.COLUMNS</code> or <code class="literal">SELECT
        COLLATION_NAME FROM INFORMATION_SCHEMA.COLUMNS</code>, users
        will see the name <code class="literal">utf8</code> or
        <code class="literal">utf8_<em class="replaceable"><code>collation_substring</code></em></code>.
      </p><p>
        <code class="literal">utf8mb3</code> is also valid in contexts other than
        <code class="literal">CHARACTER SET</code> clauses. For example:
      </p><pre data-lang="terminal" class="programlisting">
mysqld --character-set-server=utf8mb3
</pre><pre data-lang="sql" class="programlisting">
SET NAMES 'utf8mb3'; /* and other SET statements that have similar effect */
SELECT _utf8mb3 'a';
</pre><p>
        For information about data type storage as it relates to
        multibyte character sets, see
        <a class="xref" href="data-types.html#data-types-storage-reqs-strings" title="String Type Storage Requirements">String Type Storage Requirements</a>.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="charset-unicode-utf8"></a>10.9.3 The utf8 Character Set (Alias for utf8mb3)</h3>

</div>

</div>

</div>
<a class="indexterm" name="idm140091696759792"></a><a class="indexterm" name="idm140091696758752"></a><a class="indexterm" name="idm140091696757264"></a><p>
        <code class="literal">utf8</code> is an alias for the
        <code class="literal">utf8mb3</code> character set. For more information,
        see <a class="xref" href="charset.html#charset-unicode-utf8mb3" title="10.9.2 The utf8mb3 Character Set (3-Byte UTF-8 Unicode Encoding)">Section 10.9.2, “The utf8mb3 Character Set (3-Byte UTF-8 Unicode Encoding)”</a>.
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Note
</div>
<p>
          The <code class="literal">utf8mb3</code> character set is deprecated and
          will be removed in a future MySQL release. Please use
          <code class="literal">utf8mb4</code> instead. Although
          <code class="literal">utf8</code> is currently an alias for
          <code class="literal">utf8mb3</code>, at some point
          <code class="literal">utf8</code> will become a reference to
          <code class="literal">utf8mb4</code>. To avoid ambiguity about the
          meaning of <code class="literal">utf8</code>, consider specifying
          <code class="literal">utf8mb4</code> explicitly for character set
          references instead of <code class="literal">utf8</code>.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="charset-unicode-ucs2"></a>10.9.4 The ucs2 Character Set (UCS-2 Unicode Encoding)</h3>

</div>

</div>

</div>
<a class="indexterm" name="idm140091696744224"></a><p>
        In UCS-2, every character is represented by a 2-byte Unicode
        code with the most significant byte first. For example:
        <code class="literal">LATIN CAPITAL LETTER A</code> has the code
        <code class="literal">0x0041</code> and it is stored as a 2-byte sequence:
        <code class="literal">0x00 0x41</code>. <code class="literal">CYRILLIC SMALL LETTER
        YERU</code> (Unicode <code class="literal">0x044B</code>) is stored as
        a 2-byte sequence: <code class="literal">0x04 0x4B</code>. For Unicode
        characters and their codes, please refer to the
        <a class="ulink" href="http://www.unicode.org/" target="_top">Unicode Consortium
        website</a>.
      </p><p>
        The <code class="literal">ucs2</code> character set has these
        characteristics:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            Supports BMP characters only (no support for supplementary
            characters)
          </p></li><li class="listitem"><p>
            Uses a fixed-length 16-bit encoding and requires two bytes
            per character.
</p></li></ul>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="charset-unicode-utf16"></a>10.9.5 The utf16 Character Set (UTF-16 Unicode Encoding)</h3>

</div>

</div>

</div>
<a class="indexterm" name="idm140091696732768"></a><p>
        The <code class="literal">utf16</code> character set is the
        <code class="literal">ucs2</code> character set with an extension that
        enables encoding of supplementary characters:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            For a BMP character, <code class="literal">utf16</code> and
            <code class="literal">ucs2</code> have identical storage
            characteristics: same code values, same encoding, same
            length.
          </p></li><li class="listitem"><p>
            For a supplementary character, <code class="literal">utf16</code> has
            a special sequence for representing the character using 32
            bits. This is called the <span class="quote">“<span class="quote">surrogate</span>”</span> mechanism:
            For a number greater than <code class="literal">0xffff</code>, take 10
            bits and add them to <code class="literal">0xd800</code> and put them
            in the first 16-bit word, take 10 more bits and add them to
            <code class="literal">0xdc00</code> and put them in the next 16-bit
            word. Consequently, all supplementary characters require 32
            bits, where the first 16 bits are a number between
            <code class="literal">0xd800</code> and <code class="literal">0xdbff</code>, and
            the last 16 bits are a number between
            <code class="literal">0xdc00</code> and <code class="literal">0xdfff</code>.
            Examples are in Section
            <a class="ulink" href="http://www.unicode.org/versions/Unicode4.0.0/ch15.pdf" target="_top">15.5
            Surrogates Area</a> of the Unicode 4.0 document.
</p></li></ul>
</div>
<p>
        Because <code class="literal">utf16</code> supports surrogates and
        <code class="literal">ucs2</code> does not, there is a validity check that
        applies only in <code class="literal">utf16</code>: You cannot insert a
        top surrogate without a bottom surrogate, or vice versa. For
        example:
      </p><pre data-lang="sql" class="programlisting">
INSERT INTO t (ucs2_column) VALUES (0xd800); /* legal */
INSERT INTO t (utf16_column)VALUES (0xd800); /* illegal */
</pre><p>
        There is no validity check for characters that are technically
        valid but are not true Unicode (that is, characters that Unicode
        considers to be <span class="quote">“<span class="quote">unassigned code points</span>”</span> or
        <span class="quote">“<span class="quote">private use</span>”</span> characters or even
        <span class="quote">“<span class="quote">illegals</span>”</span> like <code class="literal">0xffff</code>). For
        example, since <code class="literal">U+F8FF</code> is the Apple Logo, this
        is legal:
      </p><pre data-lang="sql" class="programlisting">
INSERT INTO t (utf16_column)VALUES (0xf8ff); /* legal */
</pre><p>
        Such characters cannot be expected to mean the same thing to
        everyone.
      </p><p>
        Because MySQL must allow for the worst case (that one character
        requires four bytes) the maximum length of a
        <code class="literal">utf16</code> column or index is only half of the
        maximum length for a <code class="literal">ucs2</code> column or index.
        For example, the maximum length of a <code class="literal">MEMORY</code>
        table index key is 3072 bytes, so these statements create tables
        with the longest permitted indexes for <code class="literal">ucs2</code>
        and <code class="literal">utf16</code> columns:
      </p><pre data-lang="sql" class="programlisting">
CREATE TABLE tf (s1 VARCHAR(1536) CHARACTER SET ucs2) ENGINE=MEMORY;
CREATE INDEX i ON tf (s1);
CREATE TABLE tg (s1 VARCHAR(768) CHARACTER SET utf16) ENGINE=MEMORY;
CREATE INDEX i ON tg (s1);
</pre>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="charset-unicode-utf16le"></a>10.9.6 The utf16le Character Set (UTF-16LE Unicode Encoding)</h3>

</div>

</div>

</div>
<a class="indexterm" name="idm140091696703328"></a><p>
        This is the same as <code class="literal">utf16</code> but is
        little-endian rather than big-endian.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="charset-unicode-utf32"></a>10.9.7 The utf32 Character Set (UTF-32 Unicode Encoding)</h3>

</div>

</div>

</div>
<a class="indexterm" name="idm140091696699744"></a><p>
        The <code class="literal">utf32</code> character set is fixed length (like
        <code class="literal">ucs2</code> and unlike <code class="literal">utf16</code>).
        <code class="literal">utf32</code> uses 32 bits for every character,
        unlike <code class="literal">ucs2</code> (which uses 16 bits for every
        character), and unlike <code class="literal">utf16</code> (which uses 16
        bits for some characters and 32 bits for others).
      </p><p>
        <code class="literal">utf32</code> takes twice as much space as
        <code class="literal">ucs2</code> and more space than
        <code class="literal">utf16</code>, but <code class="literal">utf32</code> has the
        same advantage as <code class="literal">ucs2</code> that it is predictable
        for storage: The required number of bytes for
        <code class="literal">utf32</code> equals the number of characters times
        4. Also, unlike <code class="literal">utf16</code>, there are no tricks
        for encoding in <code class="literal">utf32</code>, so the stored value
        equals the code value.
      </p><p>
        To demonstrate how the latter advantage is useful, here is an
        example that shows how to determine a <code class="literal">utf8mb4</code>
        value given the <code class="literal">utf32</code> code value:
      </p><pre data-lang="sql" class="programlisting">
/* Assume code value = 100cc LINEAR B WHEELED CHARIOT */
CREATE TABLE tmp (utf32_col CHAR(1) CHARACTER SET utf32,
                  utf8mb4_col CHAR(1) CHARACTER SET utf8mb4);
INSERT INTO tmp VALUES (0x000100cc,NULL);
UPDATE tmp SET utf8mb4_col = utf32_col;
SELECT HEX(utf32_col),HEX(utf8mb4_col) FROM tmp;
</pre><p>
        MySQL is very forgiving about additions of unassigned Unicode
        characters or private-use-area characters. There is in fact only
        one validity check for <code class="literal">utf32</code>: No code value
        may be greater than <code class="literal">0x10ffff</code>. For example,
        this is illegal:
      </p><pre data-lang="sql" class="programlisting">
INSERT INTO t (utf32_column) VALUES (0x110000); /* illegal */
</pre>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="charset-unicode-conversion"></a>10.9.8 Converting Between 3-Byte and 4-Byte Unicode Character Sets</h3>

</div>

</div>

</div>
<p>
        This section describes issues that you may face when converting
        character data between the <code class="literal">utf8mb3</code> and
        <code class="literal">utf8mb4</code> character sets.
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Note
</div>
<p>
          This discussion focuses primarily on converting between
          <code class="literal">utf8mb3</code> and <code class="literal">utf8mb4</code>, but
          similar principles apply to converting between the
          <code class="literal">ucs2</code> character set and character sets such
          as <code class="literal">utf16</code> or <code class="literal">utf32</code>.
</p>
</div>
<p>
        The <code class="literal">utf8mb3</code> and <code class="literal">utf8mb4</code>
        character sets differ as follows:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            <code class="literal">utf8mb3</code> supports only characters in the
            Basic Multilingual Plane (BMP). <code class="literal">utf8mb4</code>
            additionally supports supplementary characters that lie
            outside the BMP.
          </p></li><li class="listitem"><p>
            <code class="literal">utf8mb3</code> uses a maximum of three bytes per
            character. <code class="literal">utf8mb4</code> uses a maximum of four
            bytes per character.
</p></li></ul>
</div>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<div class="admon-title">
Note
</div>
<p>
          This discussion refers to the <code class="literal">utf8mb3</code> and
          <code class="literal">utf8mb4</code> character set names to be explicit
          about referring to 3-byte and 4-byte UTF-8 character set data.
          The exception is that in table definitions,
          <code class="literal">utf8</code> is used because MySQL converts
          instances of <code class="literal">utf8mb3</code> specified in such
          definitions to <code class="literal">utf8</code>, which is an alias for
          <code class="literal">utf8mb3</code>.
</p>
</div>
<p>
        One advantage of converting from <code class="literal">utf8mb3</code> to
        <code class="literal">utf8mb4</code> is that this enables applications to
        use supplementary characters. One tradeoff is that this may
        increase data storage space requirements.
      </p><p>
        In terms of table content, conversion from
        <code class="literal">utf8mb3</code> to <code class="literal">utf8mb4</code>
        presents no problems:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            For a BMP character, <code class="literal">utf8mb4</code> and
            <code class="literal">utf8mb3</code> have identical storage
            characteristics: same code values, same encoding, same
            length.
          </p></li><li class="listitem"><p>
            For a supplementary character, <code class="literal">utf8mb4</code>
            requires four bytes to store it, whereas
            <code class="literal">utf8mb3</code> cannot store the character at
            all. When converting <code class="literal">utf8mb3</code> columns to
            <code class="literal">utf8mb4</code>, you need not worry about
            converting supplementary characters because there will be
            none.
</p></li></ul>
</div>
<p>
        In terms of table structure, these are the primary potential
        incompatibilities:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            For the variable-length character data types
            (<a class="link" href="data-types.html#char" title="11.4.1 The CHAR and VARCHAR Types"><code class="literal">VARCHAR</code></a> and the
            <a class="link" href="data-types.html#blob" title="11.4.3 The BLOB and TEXT Types"><code class="literal">TEXT</code></a> types), the maximum
            permitted length in characters is less for
            <code class="literal">utf8mb4</code> columns than for
            <code class="literal">utf8mb3</code> columns.
          </p></li><li class="listitem"><p>
            For all character data types
            (<a class="link" href="data-types.html#char" title="11.4.1 The CHAR and VARCHAR Types"><code class="literal">CHAR</code></a>,
            <a class="link" href="data-types.html#char" title="11.4.1 The CHAR and VARCHAR Types"><code class="literal">VARCHAR</code></a>, and the
            <a class="link" href="data-types.html#blob" title="11.4.3 The BLOB and TEXT Types"><code class="literal">TEXT</code></a> types), the maximum
            number of characters that can be indexed is less for
            <code class="literal">utf8mb4</code> columns than for
            <code class="literal">utf8mb3</code> columns.
</p></li></ul>
</div>
<p>
        Consequently, to convert tables from <code class="literal">utf8mb3</code>
        to <code class="literal">utf8mb4</code>, it may be necessary to change
        some column or index definitions.
      </p><p>
        Tables can be converted from <code class="literal">utf8mb3</code> to
        <code class="literal">utf8mb4</code> by using <a class="link" href="sql-syntax.html#alter-table" title="13.1.9 ALTER TABLE Syntax"><code class="literal">ALTER
        TABLE</code></a>. Suppose that a table has this definition:
      </p><pre data-lang="sql" class="programlisting">
CREATE TABLE t1 (
  col1 CHAR(10) CHARACTER SET utf8 COLLATE utf8_unicode_ci NOT NULL,
  col2 CHAR(10) CHARACTER SET utf8 COLLATE utf8_bin NOT NULL
) CHARACTER SET utf8;
</pre><p>
        The following statement converts <code class="literal">t1</code> to use
        <code class="literal">utf8mb4</code>:
      </p><pre data-lang="sql" class="programlisting">
ALTER TABLE t1
  DEFAULT CHARACTER SET utf8mb4,
  MODIFY col1 CHAR(10)
    CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci NOT NULL,
  MODIFY col2 CHAR(10)
    CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL;
</pre><p>
        The catch when converting from <code class="literal">utf8mb3</code> to
        <code class="literal">utf8mb4</code> is that the maximum length of a
        column or index key is unchanged in terms of
        <span class="emphasis"><em>bytes</em></span>. Therefore, it is smaller in terms of
        <span class="emphasis"><em>characters</em></span> because the maximum length of a
        character is four bytes instead of three. For the
        <a class="link" href="data-types.html#char" title="11.4.1 The CHAR and VARCHAR Types"><code class="literal">CHAR</code></a>,
        <a class="link" href="data-types.html#char" title="11.4.1 The CHAR and VARCHAR Types"><code class="literal">VARCHAR</code></a>, and
        <a class="link" href="data-types.html#blob" title="11.4.3 The BLOB and TEXT Types"><code class="literal">TEXT</code></a> data types, watch for these
        issues when converting your MySQL tables:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            Check all definitions of <code class="literal">utf8mb3</code> columns
            and make sure they will not exceed the maximum length for
            the storage engine.
          </p></li><li class="listitem"><p>
            Check all indexes on <code class="literal">utf8mb3</code> columns and
            make sure they will not exceed the maximum length for the
            storage engine. Sometimes the maximum can change due to
            storage engine enhancements.
</p></li></ul>
</div>
<p>
        If the preceding conditions apply, you must either reduce the
        defined length of columns or indexes, or continue to use
        <code class="literal">utf8mb3</code> rather than
        <code class="literal">utf8mb4</code>.
      </p><p>
        Here are some examples where structural changes may be needed:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            A <a class="link" href="data-types.html#blob" title="11.4.3 The BLOB and TEXT Types"><code class="literal">TINYTEXT</code></a> column can hold up
            to 255 bytes, so it can hold up to 85 3-byte or 63 4-byte
            characters. Suppose that you have a
            <a class="link" href="data-types.html#blob" title="11.4.3 The BLOB and TEXT Types"><code class="literal">TINYTEXT</code></a> column that uses
            <code class="literal">utf8mb3</code> but must be able to contain more
            than 63 characters. You cannot convert it to
            <code class="literal">utf8mb4</code> unless you also change the data
            type to a longer type such as
            <a class="link" href="data-types.html#blob" title="11.4.3 The BLOB and TEXT Types"><code class="literal">TEXT</code></a>.
          </p><p>
            Similarly, a very long
            <a class="link" href="data-types.html#char" title="11.4.1 The CHAR and VARCHAR Types"><code class="literal">VARCHAR</code></a> column may need to be
            changed to one of the longer
            <a class="link" href="data-types.html#blob" title="11.4.3 The BLOB and TEXT Types"><code class="literal">TEXT</code></a> types if you want to
            convert it from <code class="literal">utf8mb3</code> to
            <code class="literal">utf8mb4</code>.
          </p></li><li class="listitem"><p>
            <code class="literal">InnoDB</code> has a maximum index length of 767
            bytes for tables that use
            <code class="literal"><a class="link" href="glossary.html#glos_compact_row_format" title="compact row format">COMPACT</a></code>
            or
            <code class="literal"><a class="link" href="glossary.html#glos_redundant_row_format" title="redundant row format">REDUNDANT</a></code>
            row format, so for <code class="literal">utf8mb3</code> or
            <code class="literal">utf8mb4</code> columns, you can index a maximum
            of 255 or 191 characters, respectively. If you currently
            have <code class="literal">utf8mb3</code> columns with indexes longer
            than 191 characters, you must index a smaller number of
            characters.
          </p><p>
            In an <code class="literal">InnoDB</code> table that uses
            <code class="literal"><a class="link" href="glossary.html#glos_compact_row_format" title="compact row format">COMPACT</a></code>
            or
            <code class="literal"><a class="link" href="glossary.html#glos_redundant_row_format" title="redundant row format">REDUNDANT</a></code>
            row format, these column and index definitions are legal:
          </p><pre data-lang="sql" class="programlisting">
col1 VARCHAR(500) CHARACTER SET utf8, INDEX (col1(255))
</pre><p>
            To use <code class="literal">utf8mb4</code> instead, the index must be
            smaller:
          </p><pre data-lang="sql" class="programlisting">
col1 VARCHAR(500) CHARACTER SET utf8mb4, INDEX (col1(191))
</pre>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Note
</div>
<p>
              For <code class="literal">InnoDB</code> tables that use
              <code class="literal"><a class="link" href="glossary.html#glos_compressed_row_format" title="compressed row format">COMPRESSED</a></code>
              or
              <code class="literal"><a class="link" href="glossary.html#glos_dynamic_row_format" title="dynamic row format">DYNAMIC</a></code>
              row format, <a class="link" href="glossary.html#glos_index_prefix" title="index prefix">index key
              prefixes</a> longer than 767 bytes (up to 3072 bytes)
              are permitted. Tables created with these row formats
              enable you to index a maximum of 1024 or 768 characters
              for <code class="literal">utf8mb3</code> or
              <code class="literal">utf8mb4</code> columns, respectively. For
              related information, see
              <a class="xref" href="innodb-storage-engine.html#innodb-restrictions" title="15.6.1.6 Limits on InnoDB Tables">Section 15.6.1.6, “Limits on InnoDB Tables”</a>, and
              <a class="xref" href="innodb-storage-engine.html#innodb-row-format-dynamic" title="DYNAMIC Row Format">DYNAMIC Row Format</a>.
</p>
</div>
</li></ul>
</div>
<p>
        The preceding types of changes are most likely to be required
        only if you have very long columns or indexes. Otherwise, you
        should be able to convert your tables from
        <code class="literal">utf8mb3</code> to <code class="literal">utf8mb4</code> without
        problems, using <a class="link" href="sql-syntax.html#alter-table" title="13.1.9 ALTER TABLE Syntax"><code class="literal">ALTER TABLE</code></a> as
        described previously.
      </p><p>
        The following items summarize other potential incompatibilities:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            <code class="literal">SET NAMES 'utf8mb4'</code> causes use of the
            4-byte character set for connection character sets. As long
            as no 4-byte characters are sent from the server, there
            should be no problems. Otherwise, applications that expect
            to receive a maximum of three bytes per character may have
            problems. Conversely, applications that expect to send
            4-byte characters must ensure that the server understands
            them.
          </p></li><li class="listitem"><p>
            For replication, if character sets that support
            supplementary characters are to be used on the master, all
            slaves must understand them as well.
          </p><p>
            Also, keep in mind the general principle that if a table has
            different definitions on the master and slave, this can lead
            to unexpected results. For example, the differences in
            maximum index key length make it risky to use
            <code class="literal">utf8mb3</code> on the master and
            <code class="literal">utf8mb4</code> on the slave.
</p></li></ul>
</div>
<p>
        If you have converted to <code class="literal">utf8mb4</code>,
        <code class="literal">utf16</code>, <code class="literal">utf16le</code>, or
        <code class="literal">utf32</code>, and then decide to convert back to
        <code class="literal">utf8mb3</code> or <code class="literal">ucs2</code> (for
        example, to downgrade to an older version of MySQL), these
        considerations apply:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            <code class="literal">utf8mb3</code> and <code class="literal">ucs2</code> data
            should present no problems.
          </p></li><li class="listitem"><p>
            The server must be recent enough to recognize definitions
            referring to the character set from which you are
            converting.
          </p></li><li class="listitem"><p>
            For object definitions that refer to the
            <code class="literal">utf8mb4</code> character set, you can dump them
            with <a class="link" href="programs.html#mysqldump" title="4.5.4 mysqldump — A Database Backup Program"><span class="command"><strong>mysqldump</strong></span></a> prior to downgrading, edit
            the dump file to change instances of
            <code class="literal">utf8mb4</code> to <code class="literal">utf8</code>, and
            reload the file in the older server, as long as there are no
            4-byte characters in the data. The older server will see
            <code class="literal">utf8</code> in the dump file object definitions
            and create new objects that use the (3-byte)
            <code class="literal">utf8</code> character set.
</p></li></ul>
</div>

</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both"><a name="charset-charsets"></a>10.10 Supported Character Sets and Collations</h2>

</div>

</div>

</div>
<div class="toc">
<dl class="toc"><dt><span class="section"><a href="charset.html#charset-unicode-sets">10.10.1 Unicode Character Sets</a></span></dt><dt><span class="section"><a href="charset.html#charset-we-sets">10.10.2 West European Character Sets</a></span></dt><dt><span class="section"><a href="charset.html#charset-ce-sets">10.10.3 Central European Character Sets</a></span></dt><dt><span class="section"><a href="charset.html#charset-se-me-sets">10.10.4 South European and Middle East Character Sets</a></span></dt><dt><span class="section"><a href="charset.html#charset-baltic-sets">10.10.5 Baltic Character Sets</a></span></dt><dt><span class="section"><a href="charset.html#charset-cyrillic-sets">10.10.6 Cyrillic Character Sets</a></span></dt><dt><span class="section"><a href="charset.html#charset-asian-sets">10.10.7 Asian Character Sets</a></span></dt><dt><span class="section"><a href="charset.html#charset-binary-set">10.10.8 The Binary Character Set</a></span></dt></dl>
</div>
<p>
      This section indicates which character sets MySQL supports. There
      is one subsection for each group of related character sets. For
      each character set, the permissible collations are listed.
    </p><p>
      To list the available character sets and their default collations,
      use the <a class="link" href="sql-syntax.html#show-character-set" title="13.7.6.3 SHOW CHARACTER SET Syntax"><code class="literal">SHOW CHARACTER SET</code></a>
      statement or query the <code class="literal">INFORMATION_SCHEMA</code>
      <a class="link" href="information-schema.html#character-sets-table" title="25.2 The INFORMATION_SCHEMA CHARACTER_SETS Table"><code class="literal">CHARACTER_SETS</code></a> table. For example:
    </p><pre data-lang="sql" class="programlisting">
mysql&gt; <strong class="userinput"><code>SHOW CHARACTER SET;</code></strong>
+----------+---------------------------------+---------------------+--------+
| Charset  | Description                     | Default collation   | Maxlen |
+----------+---------------------------------+---------------------+--------+
| armscii8 | ARMSCII-8 Armenian              | armscii8_general_ci |      1 |
| ascii    | US ASCII                        | ascii_general_ci    |      1 |
| big5     | Big5 Traditional Chinese        | big5_chinese_ci     |      2 |
| binary   | Binary pseudo charset           | binary              |      1 |
| cp1250   | Windows Central European        | cp1250_general_ci   |      1 |
| cp1251   | Windows Cyrillic                | cp1251_general_ci   |      1 |
| cp1256   | Windows Arabic                  | cp1256_general_ci   |      1 |
| cp1257   | Windows Baltic                  | cp1257_general_ci   |      1 |
| cp850    | DOS West European               | cp850_general_ci    |      1 |
| cp852    | DOS Central European            | cp852_general_ci    |      1 |
| cp866    | DOS Russian                     | cp866_general_ci    |      1 |
| cp932    | SJIS for Windows Japanese       | cp932_japanese_ci   |      2 |
| dec8     | DEC West European               | dec8_swedish_ci     |      1 |
| eucjpms  | UJIS for Windows Japanese       | eucjpms_japanese_ci |      3 |
| euckr    | EUC-KR Korean                   | euckr_korean_ci     |      2 |
| gb18030  | China National Standard GB18030 | gb18030_chinese_ci  |      4 |
| gb2312   | GB2312 Simplified Chinese       | gb2312_chinese_ci   |      2 |
| gbk      | GBK Simplified Chinese          | gbk_chinese_ci      |      2 |
| geostd8  | GEOSTD8 Georgian                | geostd8_general_ci  |      1 |
| greek    | ISO 8859-7 Greek                | greek_general_ci    |      1 |
| hebrew   | ISO 8859-8 Hebrew               | hebrew_general_ci   |      1 |
| hp8      | HP West European                | hp8_english_ci      |      1 |
| keybcs2  | DOS Kamenicky Czech-Slovak      | keybcs2_general_ci  |      1 |
| koi8r    | KOI8-R Relcom Russian           | koi8r_general_ci    |      1 |
| koi8u    | KOI8-U Ukrainian                | koi8u_general_ci    |      1 |
| latin1   | cp1252 West European            | latin1_swedish_ci   |      1 |
| latin2   | ISO 8859-2 Central European     | latin2_general_ci   |      1 |
| latin5   | ISO 8859-9 Turkish              | latin5_turkish_ci   |      1 |
| latin7   | ISO 8859-13 Baltic              | latin7_general_ci   |      1 |
| macce    | Mac Central European            | macce_general_ci    |      1 |
| macroman | Mac West European               | macroman_general_ci |      1 |
| sjis     | Shift-JIS Japanese              | sjis_japanese_ci    |      2 |
| swe7     | 7bit Swedish                    | swe7_swedish_ci     |      1 |
| tis620   | TIS620 Thai                     | tis620_thai_ci      |      1 |
| ucs2     | UCS-2 Unicode                   | ucs2_general_ci     |      2 |
| ujis     | EUC-JP Japanese                 | ujis_japanese_ci    |      3 |
| utf16    | UTF-16 Unicode                  | utf16_general_ci    |      4 |
| utf16le  | UTF-16LE Unicode                | utf16le_general_ci  |      4 |
| utf32    | UTF-32 Unicode                  | utf32_general_ci    |      4 |
| utf8     | UTF-8 Unicode                   | utf8_general_ci     |      3 |
| utf8mb4  | UTF-8 Unicode                   | utf8mb4_0900_ai_ci  |      4 |
+----------+---------------------------------+---------------------+--------+
</pre><p>
      In cases where a character set has multiple collations, it might
      not be clear which collation is most suitable for a given
      application. To avoid choosing the wrong collation, it can be
      helpful to perform some comparisons with representative data
      values to make sure that a given collation sorts values the way
      you expect.
</p>
<div class="section">

<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="charset-unicode-sets"></a>10.10.1 Unicode Character Sets</h3>
</div>
</div>
</div>
<a class="indexterm" name="idm140091696543888"></a><a class="indexterm" name="idm140091696542400"></a><p>
        This section describes the collations available for Unicode
        character sets and their differentiating properties. For general
        information about Unicode, see
        <a class="xref" href="charset.html#charset-unicode" title="10.9 Unicode Support">Section 10.9, “Unicode Support”</a>.
      </p><p>
        MySQL supports multiple Unicode character sets:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            <code class="literal">utf8mb4</code>: A UTF-8 encoding of the Unicode
            character set using one to four bytes per character.
          </p></li><li class="listitem"><p>
            <code class="literal">utf8mb3</code>: A UTF-8 encoding of the Unicode
            character set using one to three bytes per character.
          </p></li><li class="listitem"><p>
            <code class="literal">utf8</code>: An alias for
            <code class="literal">utf8mb3</code>.
          </p></li><li class="listitem"><p>
            <code class="literal">ucs2</code>: The UCS-2 encoding of the Unicode
            character set using two bytes per character.
          </p></li><li class="listitem"><p>
            <code class="literal">utf16</code>: The UTF-16 encoding for the
            Unicode character set using two or four bytes per character.
            Like <code class="literal">ucs2</code> but with an extension for
            supplementary characters.
          </p></li><li class="listitem"><p>
            <code class="literal">utf16le</code>: The UTF-16LE encoding for the
            Unicode character set. Like <code class="literal">utf16</code> but
            little-endian rather than big-endian.
          </p></li><li class="listitem"><p>
            <code class="literal">utf32</code>: The UTF-32 encoding for the
            Unicode character set using four bytes per character.
</p></li></ul>
</div>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<div class="admon-title">
Note
</div>
<p>
          The <code class="literal">utf8mb3</code> character set is deprecated and
          will be removed in a future MySQL release. Please use
          <code class="literal">utf8mb4</code> instead. Although
          <code class="literal">utf8</code> is currently an alias for
          <code class="literal">utf8mb3</code>, at some point
          <code class="literal">utf8</code> will become a reference to
          <code class="literal">utf8mb4</code>. To avoid ambiguity about the
          meaning of <code class="literal">utf8</code>, consider specifying
          <code class="literal">utf8mb4</code> explicitly for character set
          references instead of <code class="literal">utf8</code>.
</p>
</div>
<p>
        <code class="literal">utf8mb4</code>, <code class="literal">utf16</code>,
        <code class="literal">utf16le</code>, and <code class="literal">utf32</code> support
        Basic Multilingual Plane (BMP) characters and supplementary
        characters that lie outside the BMP. <code class="literal">utf8</code> and
        <code class="literal">ucs2</code> support only BMP characters.
      </p><p>
        Most Unicode character sets have a general collation (indicated
        by <code class="literal">_general</code> in the name or by the absence of
        a language specifier), a binary collation (indicated by
        <code class="literal">_bin</code> in the name), and several
        language-specific collations (indicated by language specifiers).
        For example, for <code class="literal">utf8mb4</code>,
        <code class="literal">utf8mb4_general_ci</code> and
        <code class="literal">utf8mb4_bin</code> are its general and binary
        collations, and <code class="literal">utf8mb4_danish_ci</code> is one of
        its language-specific collations.
      </p><a class="indexterm" name="idm140091696507216"></a><a class="indexterm" name="idm140091696505728"></a><p>
        Most character sets have a single binary collation.
        <code class="literal">utf8mb4</code> is an exception that has two:
        <code class="literal">utf8mb4_bin</code> and (as of MySQL 8.0.17)
        <code class="literal">utf8mb4_0900_bin</code>. These two binary collations
        have the same sort order but are distinguished by their pad
        attribute and collating weight characteristics. See
        <a class="xref" href="charset.html#charset-unicode-sets-pad-attributes" title="Collation Pad Attributes">Collation Pad Attributes</a>, and
        <a class="xref" href="charset.html#charset-unicode-sets-collating-weights" title="Character Collating Weights">Character Collating Weights</a>.
      </p><p>
        Collation support for <code class="literal">utf16le</code> is limited. The
        only collations available are
        <code class="literal">utf16le_general_ci</code> and
        <code class="literal">utf16le_bin</code>. These are similar to
        <code class="literal">utf16_general_ci</code> and
        <code class="literal">utf16_bin</code>.
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><a class="xref" href="charset.html#charset-unicode-sets-uca" title="Unicode Collation Algorithm (UCA) Versions">Unicode Collation Algorithm (UCA) Versions</a></p></li><li class="listitem"><p><a class="xref" href="charset.html#charset-unicode-sets-pad-attributes" title="Collation Pad Attributes">Collation Pad Attributes</a></p></li><li class="listitem"><p><a class="xref" href="charset.html#charset-unicode-sets-language-specific-collations" title="Language-Specific Collations">Language-Specific Collations</a></p></li><li class="listitem"><p><a class="xref" href="charset.html#charset-unicode-sets-general-versus-unicode" title="_general_ci Versus _unicode_ci Collations">_general_ci Versus _unicode_ci Collations</a></p></li><li class="listitem"><p><a class="xref" href="charset.html#charset-unicode-sets-collating-weights" title="Character Collating Weights">Character Collating Weights</a></p></li><li class="listitem"><p><a class="xref" href="charset.html#charset-unicode-sets-miscellaneous" title="Miscellaneous Information">Miscellaneous Information</a></p></li></ul>
</div>

<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h4 class="title"><a name="charset-unicode-sets-uca"></a>Unicode Collation Algorithm (UCA) Versions</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140091696487888"></a><p>
          MySQL implements the
          <code class="literal"><em class="replaceable"><code>xxx</code></em>_unicode_ci</code>
          collations according to the Unicode Collation Algorithm (UCA)
          described at
          <a class="ulink" href="http://www.unicode.org/reports/tr10/" target="_top">http://www.unicode.org/reports/tr10/</a>. The
          collation uses the version-4.0.0 UCA weight keys:
          <a class="ulink" href="http://www.unicode.org/Public/UCA/4.0.0/allkeys-4.0.0.txt" target="_top">http://www.unicode.org/Public/UCA/4.0.0/allkeys-4.0.0.txt</a>.
          The
          <code class="literal"><em class="replaceable"><code>xxx</code></em>_unicode_ci</code>
          collations have only partial support for the Unicode Collation
          Algorithm. Some characters are not supported, and combining
          marks are not fully supported. This affects primarily
          Vietnamese, Yoruba, and some smaller languages such as Navajo.
          A combined character is considered different from the same
          character written with a single unicode character in string
          comparisons, and the two characters are considered to have a
          different length (for example, as returned by the
          <a class="link" href="functions.html#function_char-length"><code class="literal">CHAR_LENGTH()</code></a> function or in
          result set metadata).
        </p><p>
          Unicode collations based on UCA versions higher than 4.0.0
          include the version in the collation name. Examples:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              <code class="literal">utf8mb4_unicode_520_ci</code> is based on UCA
              5.2.0 weight keys
              (<a class="ulink" href="http://www.unicode.org/Public/UCA/5.2.0/allkeys.txt" target="_top">http://www.unicode.org/Public/UCA/5.2.0/allkeys.txt</a>),
            </p></li><li class="listitem"><p>
              <code class="literal">utf8mb4_0900_ai_ci</code> is based on UCA
              9.0.0 weight keys
              (<a class="ulink" href="http://www.unicode.org/Public/UCA/9.0.0/allkeys.txt" target="_top">http://www.unicode.org/Public/UCA/9.0.0/allkeys.txt</a>).
</p></li></ul>
</div>
<p>
          The <a class="link" href="functions.html#function_lower"><code class="literal">LOWER()</code></a> and
          <a class="link" href="functions.html#function_upper"><code class="literal">UPPER()</code></a> functions perform case
          folding according to the collation of their argument. A
          character that has uppercase and lowercase versions only in a
          Unicode version higher than 4.0.0 is converted by these
          functions only if the argument collation uses a high enough
          UCA version.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h4 class="title"><a name="charset-unicode-sets-pad-attributes"></a>Collation Pad Attributes</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140091696471376"></a><a class="indexterm" name="idm140091696469888"></a><a class="indexterm" name="idm140091696468816"></a><a class="indexterm" name="idm140091696467328"></a><p>
          Collations based on UCA 9.0.0 and higher are faster than
          collations based on UCA versions prior to 9.0.0. They also
          have a pad attribute of <code class="literal">NO PAD</code>, in contrast
          to <code class="literal">PAD SPACE</code> as used in collations based on
          UCA versions prior to 9.0.0. For comparison of nonbinary
          strings, <code class="literal">NO PAD</code> collations treat spaces at
          the end of strings like any other character (see
          <a class="xref" href="charset.html#charset-binary-collations-trailing-space-comparisons" title="Trailing Space Handling in Comparisons">Trailing Space Handling in Comparisons</a>).
        </p><p>
          To determine the pad attribute for a collation, use the
          <code class="literal">INFORMATION_SCHEMA</code>
          <a class="link" href="information-schema.html#collations-table" title="25.4 The INFORMATION_SCHEMA COLLATIONS Table"><code class="literal">COLLATIONS</code></a> table, which has a
          <code class="literal">PAD_ATTRIBUTE</code> column. For example:
        </p><pre data-lang="sql" class="programlisting">
mysql&gt; <strong class="userinput"><code>SELECT COLLATION_NAME, PAD_ATTRIBUTE</code></strong>
       <strong class="userinput"><code>FROM INFORMATION_SCHEMA.COLLATIONS</code></strong>
       <strong class="userinput"><code>WHERE CHARACTER_SET_NAME = 'utf8mb4';</code></strong>
+----------------------------+---------------+
| COLLATION_NAME             | PAD_ATTRIBUTE |
+----------------------------+---------------+
| utf8mb4_general_ci         | PAD SPACE     |
| utf8mb4_bin                | PAD SPACE     |
| utf8mb4_unicode_ci         | PAD SPACE     |
| utf8mb4_icelandic_ci       | PAD SPACE     |
...
| utf8mb4_0900_ai_ci         | NO PAD        |
| utf8mb4_de_pb_0900_ai_ci   | NO PAD        |
| utf8mb4_is_0900_ai_ci      | NO PAD        |
...
| utf8mb4_ja_0900_as_cs      | NO PAD        |
| utf8mb4_ja_0900_as_cs_ks   | NO PAD        |
| utf8mb4_0900_as_ci         | NO PAD        |
| utf8mb4_ru_0900_ai_ci      | NO PAD        |
| utf8mb4_ru_0900_as_cs      | NO PAD        |
| utf8mb4_zh_0900_as_cs      | NO PAD        |
| utf8mb4_0900_bin           | NO PAD        |
+----------------------------+---------------+
</pre><p>
          Comparison of nonbinary string values
          (<code class="literal">CHAR</code>, <code class="literal">VARCHAR</code>, and
          <code class="literal">TEXT</code>) that have a <code class="literal">NO PAD</code>
          collation differ from other collations with respect to
          trailing spaces. For example, <code class="literal">'a'</code> and
          <code class="literal">'a '</code> compare as different strings, not
          the same string. This can be seen using the binary collations
          for <code class="literal">utf8mb4</code>. The pad attribute for
          <code class="literal">utf8mb4_bin</code> is <code class="literal">PAD
          SPACE</code>, whereas for
          <code class="literal">utf8mb4_0900_bin</code> it is <code class="literal">NO
          PAD</code>. Consequently, operations involving
          <code class="literal">utf8mb4_0900_bin</code> do not add trailing
          spaces, and comparisons involving strings with trailing spaces
          may differ for the two collations:
        </p><pre data-lang="sql" class="programlisting">
mysql&gt; <strong class="userinput"><code>CREATE TABLE t1 (c CHAR(10) COLLATE utf8mb4_bin);</code></strong>
Query OK, 0 rows affected (0.03 sec)

mysql&gt; <strong class="userinput"><code>INSERT INTO t1 VALUES('a');</code></strong>
Query OK, 1 row affected (0.01 sec)

mysql&gt; <strong class="userinput"><code>SELECT * FROM t1 WHERE c = 'a ';</code></strong>
+------+
| c    |
+------+
| a    |
+------+
1 row in set (0.00 sec)

mysql&gt; <strong class="userinput"><code>ALTER TABLE t1 MODIFY c CHAR(10) COLLATE utf8mb4_0900_bin;</code></strong>
Query OK, 0 rows affected (0.02 sec)
Records: 0  Duplicates: 0  Warnings: 0

mysql&gt; <strong class="userinput"><code>SELECT * FROM t1 WHERE c = 'a ';</code></strong>
Empty set (0.00 sec)
</pre>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h4 class="title"><a name="charset-unicode-sets-language-specific-collations"></a>Language-Specific Collations</h4>

</div>

</div>

</div>
<p>
          MySQL implements language-specific Unicode collations if the
          ordering based only on the Unicode Collation Algorithm (UCA)
          does not work well for a language. Language-specific
          collations are UCA-based, with additional language tailoring
          rules. Examples of such rules appear later in this section.
          For questions about particular language orderings,
          <a class="ulink" href="unicode.org" target="_top">unicode.org</a> provides Common Locale Data
          Repository (CLDR) collation charts at
          <a class="ulink" href="http://www.unicode.org/cldr/charts/30/collation/index.html" target="_top">http://www.unicode.org/cldr/charts/30/collation/index.html</a>.
        </p><a class="indexterm" name="idm140091696437504"></a><p>
          For example, the nonlanguage-specific
          <code class="literal">utf8mb4_0900_ai_ci</code> and language-specific
          <code class="literal">utf8mb4_<em class="replaceable"><code>LOCALE</code></em>_0900_ai_ci</code>
          Unicode collations each have these characteristics:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              The collation is based on UCA 9.0.0 and CLDR v30, is
              accent insensitive, and case insensitive. These
              characteristics are indicated by <code class="literal">_0900</code>,
              <code class="literal">_ai</code>, and <code class="literal">_ci</code> in the
              collation name. Exception:
              <code class="literal">utf8mb4_la_0900_ai_ci</code> is not based on
              CLDR because Classical Latin is not defined in CLDR.
            </p></li><li class="listitem"><p>
              The collation works for all characters in the range [U+0,
              U+10FFFF].
            </p></li><li class="listitem"><p>
              If the collation is not language specific, it sorts all
              characters, including supplementary characters, in default
              order (described following). If the collation is language
              specific, it sorts characters of the language correctly
              according to language-specific rules, and characters not
              in the language in default order.
            </p></li><li class="listitem"><p>
              By default, the collation sorts characters having a code
              point listed in the DUCET table (Default Unicode Collation
              Element Table) according to the weight value assigned in
              the table. The collation sorts characters not having a
              code point listed in the DUCET table using their implicit
              weight value, which is constructed according to the UCA.
            </p></li><li class="listitem"><p>
              For non-language-specific collations, characters in
              contraction sequences are treated as separate characters.
              For language-specific collations, contractions might
              change character sorting order.
</p></li></ul>
</div>
<p>
          A collation name that includes a locale code or language name
          shown in the following table is a language-specific collation.
          Unicode character sets may include collations for one or more
          of these languages.
</p>
<div class="table">
<a name="charset-unicode-collation-language-specifiers"></a><p class="title"><b>Table 10.3 Unicode Collation Language Specifiers</b></p>
<div class="table-contents">
<table summary="Language specifiers for Unicode character set collations."><col width="40%"><col width="60%"><thead><tr>
              <th scope="col">Language</th>
              <th scope="col">Language Specifier</th>
            </tr></thead><tbody><tr>
              <td scope="row">Chinese</td>
              <td><code class="literal">zh</code></td>
            </tr><tr>
              <td scope="row">Classical Latin</td>
              <td><code class="literal">la</code> or <code class="literal">roman</code></td>
            </tr><tr>
              <td scope="row">Croatian</td>
              <td><code class="literal">hr</code> or <code class="literal">croatian</code></td>
            </tr><tr>
              <td scope="row">Czech</td>
              <td><code class="literal">cs</code> or <code class="literal">czech</code></td>
            </tr><tr>
              <td scope="row">Danish</td>
              <td><code class="literal">da</code> or <code class="literal">danish</code></td>
            </tr><tr>
              <td scope="row">Esperanto</td>
              <td><code class="literal">eo</code> or <code class="literal">esperanto</code></td>
            </tr><tr>
              <td scope="row">Estonian</td>
              <td><code class="literal">et</code> or <code class="literal">estonian</code></td>
            </tr><tr>
              <td scope="row">German phone book order</td>
              <td><code class="literal">de_pb</code> or <code class="literal">german2</code></td>
            </tr><tr>
              <td scope="row">Hungarian</td>
              <td><code class="literal">hu</code> or <code class="literal">hungarian</code></td>
            </tr><tr>
              <td scope="row">Icelandic</td>
              <td><code class="literal">is</code> or <code class="literal">icelandic</code></td>
            </tr><tr>
              <td scope="row">Japanese</td>
              <td><code class="literal">ja</code></td>
            </tr><tr>
              <td scope="row">Latvian</td>
              <td><code class="literal">lv</code> or <code class="literal">latvian</code></td>
            </tr><tr>
              <td scope="row">Lithuanian</td>
              <td><code class="literal">lt</code> or <code class="literal">lithuanian</code></td>
            </tr><tr>
              <td scope="row">Persian</td>
              <td><code class="literal">persian</code></td>
            </tr><tr>
              <td scope="row">Polish</td>
              <td><code class="literal">pl</code> or <code class="literal">polish</code></td>
            </tr><tr>
              <td scope="row">Romanian</td>
              <td><code class="literal">ro</code> or <code class="literal">romanian</code></td>
            </tr><tr>
              <td scope="row">Russian</td>
              <td><code class="literal">ru</code></td>
            </tr><tr>
              <td scope="row">Sinhala</td>
              <td><code class="literal">sinhala</code></td>
            </tr><tr>
              <td scope="row">Slovak</td>
              <td><code class="literal">sk</code> or <code class="literal">slovak</code></td>
            </tr><tr>
              <td scope="row">Slovenian</td>
              <td><code class="literal">sl</code> or <code class="literal">slovenian</code></td>
            </tr><tr>
              <td scope="row">Modern Spanish</td>
              <td><code class="literal">es</code> or <code class="literal">spanish</code></td>
            </tr><tr>
              <td scope="row">Traditional Spanish</td>
              <td><code class="literal">es_trad</code> or <code class="literal">spanish2</code></td>
            </tr><tr>
              <td scope="row">Swedish</td>
              <td><code class="literal">sv</code> or <code class="literal">swedish</code></td>
            </tr><tr>
              <td scope="row">Turkish</td>
              <td><code class="literal">tr</code> or <code class="literal">turkish</code></td>
            </tr><tr>
              <td scope="row">Vietnamese</td>
              <td><code class="literal">vi</code> or <code class="literal">vietnamese</code></td>
</tr></tbody></table>
</div>

</div>
<br class="table-break"><p>
          Croatian collations are tailored for these Croatian letters:
          <code class="literal">Č</code>, <code class="literal">Ć</code>,
          <code class="literal">Dž</code>, <code class="literal">Đ</code>,
          <code class="literal">Lj</code>, <code class="literal">Nj</code>,
          <code class="literal">Š</code>, <code class="literal">Ž</code>.
        </p><p>
          Danish collations may also be used for Norwegian.
        </p><p>
          For Japanese, the <code class="literal">utf8mb4</code> character set
          includes <code class="literal">utf8mb4_ja_0900_as_cs</code> and
          <code class="literal">utf8mb4_ja_0900_as_cs_ks</code> collations. Both
          collations are accent sensitive and case-sensitive.
          <code class="literal">utf8mb4_ja_0900_as_cs_ks</code> is also kana
          sensitive and distinguishes Katakana characters from Hiragana
          characters, whereas <code class="literal">utf8mb4_ja_0900_as_cs</code>
          treats Katakana and Hiragana characters as equal for sorting.
          Applications that require a Japanese collation but not kana
          sensitivity may use <code class="literal">utf8mb4_ja_0900_as_cs</code>
          for better sort performance.
          <code class="literal">utf8mb4_ja_0900_as_cs</code> uses three weight
          levels for sorting;
          <code class="literal">utf8mb4_ja_0900_as_cs_ks</code> uses four.
        </p><p>
          For Classical Latin collations that are accent insensitive,
          <code class="literal">I</code> and <code class="literal">J</code> compare as
          equal, and <code class="literal">U</code> and <code class="literal">V</code>
          compare as equal. <code class="literal">I</code> and
          <code class="literal">J</code>, and <code class="literal">U</code> and
          <code class="literal">V</code> compare as equal on the base letter
          level. In other words, <code class="literal">J</code> is regarded as an
          accented <code class="literal">I</code>, and <code class="literal">U</code> is
          regarded as an accented <code class="literal">V</code>.
        </p><p>
          Spanish collations are available for modern and traditional
          Spanish. For both, <code class="literal">ñ</code> (n-tilde) is a
          separate letter between <code class="literal">n</code> and
          <code class="literal">o</code>. In addition, for traditional Spanish,
          <code class="literal">ch</code> is a separate letter between
          <code class="literal">c</code> and <code class="literal">d</code>, and
          <code class="literal">ll</code> is a separate letter between
          <code class="literal">l</code> and <code class="literal">m</code>.
        </p><p>
          Traditional Spanish collations may also be used for Asturian
          and Galician.
        </p><p>
          Swedish collations include Swedish rules. For example, in
          Swedish, the following relationship holds, which is not
          something expected by a German or French speaker:
        </p><pre data-lang="none" class="programlisting">
Ü = Y &lt; Ö
</pre>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h4 class="title"><a name="charset-unicode-sets-general-versus-unicode"></a>_general_ci Versus _unicode_ci Collations</h4>

</div>

</div>

</div>
<p>
          For any Unicode character set, operations performed using the
          <code class="literal"><em class="replaceable"><code>xxx</code></em>_general_ci</code>
          collation are faster than those for the
          <code class="literal"><em class="replaceable"><code>xxx</code></em>_unicode_ci</code>
          collation. For example, comparisons for the
          <code class="literal">utf8_general_ci</code> collation are faster, but
          slightly less correct, than comparisons for
          <code class="literal">utf8_unicode_ci</code>. The reason is that
          <code class="literal">utf8_unicode_ci</code> supports mappings such as
          expansions; that is, when one character compares as equal to
          combinations of other characters. For example,
          <code class="literal">ß</code> is equal to <code class="literal">ss</code> in
          German and some other languages.
          <code class="literal">utf8_unicode_ci</code> also supports contractions
          and ignorable characters. <code class="literal">utf8_general_ci</code>
          is a legacy collation that does not support expansions,
          contractions, or ignorable characters. It can make only
          one-to-one comparisons between characters.
        </p><p>
          To further illustrate, the following equalities hold in both
          <code class="literal">utf8_general_ci</code> and
          <code class="literal">utf8_unicode_ci</code> (for the effect of this in
          comparisons or searches, see
          <a class="xref" href="charset.html#charset-collation-effect" title="10.8.6 Examples of the Effect of Collation">Section 10.8.6, “Examples of the Effect of Collation”</a>):
        </p><pre data-lang="none" class="programlisting">
Ä = A
Ö = O
Ü = U
</pre><p>
          A difference between the collations is that this is true for
          <code class="literal">utf8_general_ci</code>:
        </p><pre data-lang="none" class="programlisting">
ß = s
</pre><p>
          Whereas this is true for <code class="literal">utf8_unicode_ci</code>,
          which supports the German DIN-1 ordering (also known as
          dictionary order):
        </p><pre data-lang="none" class="programlisting">
ß = ss
</pre><p>
          MySQL implements <code class="literal">utf8</code> language-specific
          collations if the ordering with
          <code class="literal">utf8_unicode_ci</code> does not work well for a
          language. For example, <code class="literal">utf8_unicode_ci</code>
          works fine for German dictionary order and French, so there is
          no need to create special <code class="literal">utf8</code> collations.
        </p><p>
          <code class="literal">utf8_general_ci</code> also is satisfactory for
          both German and French, except that <code class="literal">ß</code> is
          equal to <code class="literal">s</code>, and not to
          <code class="literal">ss</code>. If this is acceptable for your
          application, you should use <code class="literal">utf8_general_ci</code>
          because it is faster. If this is not acceptable (for example,
          if you require German dictionary order), use
          <code class="literal">utf8_unicode_ci</code> because it is more
          accurate.
        </p><p>
          If you require German DIN-2 (phone book) ordering, use the
          <code class="literal">utf8_german2_ci</code> collation, which compares
          the following sets of characters equal:
        </p><pre data-lang="none" class="programlisting">
Ä = Æ = AE
Ö = Œ = OE
Ü = UE
ß = ss
</pre><p>
          <code class="literal">utf8_german2_ci</code> is similar to
          <code class="literal">latin1_german2_ci</code>, but the latter does not
          compare <code class="literal">Æ</code> equal to <code class="literal">AE</code>
          or <code class="literal">Œ</code> equal to <code class="literal">OE</code>. There
          is no <code class="literal">utf8_german_ci</code> corresponding to
          <code class="literal">latin1_german_ci</code> for German dictionary
          order because <code class="literal">utf8_general_ci</code> suffices.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h4 class="title"><a name="charset-unicode-sets-collating-weights"></a>Character Collating Weights</h4>

</div>

</div>

</div>
<p>
          A character's collating weight is determined as follows:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              For all Unicode collations except the
              <code class="literal">_bin</code> (binary) collations, MySQL
              performs a table lookup to find a character's collating
              weight.
            </p></li><li class="listitem"><p>
              For <code class="literal">_bin</code> collations except
              <code class="literal">utf8mb4_0900_bin</code>, the weight is based
              on the code point, possibly with leading zero bytes added.
            </p></li><li class="listitem"><p>
              For <code class="literal">utf8mb4_0900_bin</code>, the weight is the
              <code class="literal">utf8mb4</code> encoding bytes. The sort order
              is the same as for <code class="literal">utf8mb4_bin</code>, but
              much faster.
</p></li></ul>
</div>
<p>
          Collating weights can be displayed using the
          <a class="link" href="functions.html#function_weight-string"><code class="literal">WEIGHT_STRING()</code></a> function. (See
          <a class="xref" href="functions.html#string-functions" title="12.5 String Functions">Section 12.5, “String Functions”</a>.) If a collation uses a
          weight lookup table, but a character is not in the table (for
          example, because it is a <span class="quote">“<span class="quote">new</span>”</span> character),
          collating weight determination becomes more complex:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              For BMP characters in general collations
              (<code class="literal"><em class="replaceable"><code>xxx</code></em>_general_ci</code>),
              the weight is the code point.
            </p></li><li class="listitem"><p>
              For BMP characters in UCA collations (for example,
              <code class="literal"><em class="replaceable"><code>xxx</code></em>_unicode_ci</code>
              and language-specific collations), the following algorithm
              applies:
            </p><pre data-lang="clike" class="programlisting">
if (code &gt;= 0x3400 &amp;&amp; code &lt;= 0x4DB5)
  base= 0xFB80; /* CJK Ideograph Extension */
else if (code &gt;= 0x4E00 &amp;&amp; code &lt;= 0x9FA5)
  base= 0xFB40; /* CJK Ideograph */
else
  base= 0xFBC0; /* All other characters */
aaaa= base +  (code &gt;&gt; 15);
bbbb= (code &amp; 0x7FFF) | 0x8000;
</pre><p>
              The result is a sequence of two collating elements,
              <code class="literal">aaaa</code> followed by
              <code class="literal">bbbb</code>. For example:
            </p><pre data-lang="sql" class="programlisting">
mysql&gt; <strong class="userinput"><code>SELECT HEX(WEIGHT_STRING(_ucs2 0x04CF COLLATE ucs2_unicode_ci));</code></strong>
+----------------------------------------------------------+
| HEX(WEIGHT_STRING(_ucs2 0x04CF COLLATE ucs2_unicode_ci)) |
+----------------------------------------------------------+
| FBC084CF                                                 |
+----------------------------------------------------------+
</pre><p>
              Thus, <code class="literal">U+04cf CYRILLIC SMALL LETTER
              PALOCHKA</code> is, with all UCA 4.0.0 collations,
              greater than <code class="literal">U+04c0 CYRILLIC LETTER
              PALOCHKA</code>. With UCA 5.2.0 collations, all
              palochkas sort together.
            </p></li><li class="listitem"><p>
              For supplementary characters in general collations, the
              weight is the weight for <code class="literal">0xfffd REPLACEMENT
              CHARACTER</code>. For supplementary characters in UCA
              4.0.0 collations, their collating weight is
              <code class="literal">0xfffd</code>. That is, to MySQL, all
              supplementary characters are equal to each other, and
              greater than almost all BMP characters.
            </p><p>
              An example with Deseret characters and
              <code class="literal">COUNT(DISTINCT)</code>:
            </p><pre data-lang="sql" class="programlisting">
CREATE TABLE t (s1 VARCHAR(5) CHARACTER SET utf32 COLLATE utf32_unicode_ci);
INSERT INTO t VALUES (0xfffd);   /* REPLACEMENT CHARACTER */
INSERT INTO t VALUES (0x010412); /* DESERET CAPITAL LETTER BEE */
INSERT INTO t VALUES (0x010413); /* DESERET CAPITAL LETTER TEE */
SELECT COUNT(DISTINCT s1) FROM t;
</pre><p>
              The result is 2 because in the MySQL
              <code class="literal"><em class="replaceable"><code>xxx</code></em>_unicode_ci</code>
              collations, the replacement character has a weight of
              <code class="literal">0x0dc6</code>, whereas Deseret Bee and Deseret
              Tee both have a weight of <code class="literal">0xfffd</code>. (Were
              the <code class="literal">utf32_general_ci</code> collation used
              instead, the result is 1 because all three characters have
              a weight of <code class="literal">0xfffd</code> in that collation.)
            </p><p>
              An example with cuneiform characters and
              <a class="link" href="functions.html#function_weight-string"><code class="literal">WEIGHT_STRING()</code></a>:
            </p><pre data-lang="sql" class="programlisting">
/*
The four characters in the INSERT string are
00000041  # LATIN CAPITAL LETTER A
0001218F  # CUNEIFORM SIGN KAB
000121A7  # CUNEIFORM SIGN KISH
00000042  # LATIN CAPITAL LETTER B
*/
CREATE TABLE t (s1 CHAR(4) CHARACTER SET utf32 COLLATE utf32_unicode_ci);
INSERT INTO t VALUES (0x000000410001218f000121a700000042);
SELECT HEX(WEIGHT_STRING(s1)) FROM t;
</pre><p>
              The result is:
            </p><pre data-lang="none" class="programlisting">
0E33 FFFD FFFD 0E4A
</pre><p>
              <code class="literal">0E33</code> and <code class="literal">0E4A</code> are
              primary weights as in
              <a class="ulink" href="ftp://www.unicode.org/Public/UCA/4.0.0/allkeys-4.0.0.txt" target="_top">UCA
              4.0.0</a>. <code class="literal">FFFD</code> is the weight for
              KAB and also for KISH.
            </p><p>
              The rule that all supplementary characters are equal to
              each other is nonoptimal but is not expected to cause
              trouble. These characters are very rare, so it is very
              rare that a multi-character string consists entirely of
              supplementary characters. In Japan, since the
              supplementary characters are obscure Kanji ideographs, the
              typical user does not care what order they are in, anyway.
              If you really want rows sorted by the MySQL rule and
              secondarily by code point value, it is easy:
            </p><pre data-lang="sql" class="programlisting">
ORDER BY s1 COLLATE utf32_unicode_ci, s1 COLLATE utf32_bin
</pre></li><li class="listitem"><p>
              For supplementary characters based on UCA versions higher
              than 4.0.0 (for example,
              <code class="literal"><em class="replaceable"><code>xxx</code></em>_unicode_520_ci</code>),
              supplementary characters do not necessarily all have the
              same collating weight. Some have explicit weights from the
              UCA <code class="filename">allkeys.txt</code> file. Others have
              weights calculated from this algorithm:
            </p><pre data-lang="clike" class="programlisting">
aaaa= base +  (code &gt;&gt; 15);
bbbb= (code &amp; 0x7FFF) | 0x8000;
</pre></li></ul>
</div>
<a class="indexterm" name="idm140091696219600"></a><p>
          There is a difference between <span class="quote">“<span class="quote">ordering by the
          character's code value</span>”</span> and <span class="quote">“<span class="quote">ordering by the
          character's binary representation,</span>”</span> a difference that
          appears only with <code class="literal">utf16_bin</code>, because of
          surrogates.
        </p><p>
          Suppose that <code class="literal">utf16_bin</code> (the binary
          collation for <code class="literal">utf16</code>) was a binary
          comparison <span class="quote">“<span class="quote">byte by byte</span>”</span> rather than
          <span class="quote">“<span class="quote">character by character.</span>”</span> If that were so, the
          order of characters in <code class="literal">utf16_bin</code> would
          differ from the order in <code class="literal">utf8_bin</code>. For
          example, the following chart shows two rare characters. The
          first character is in the range
          <code class="literal">E000</code>-<code class="literal">FFFF</code>, so it is
          greater than a surrogate but less than a supplementary. The
          second character is a supplementary.
        </p><pre data-lang="none" class="programlisting">
Code point  Character                    utf8         utf16
----------  ---------                    ----         -----
0FF9D       HALFWIDTH KATAKANA LETTER N  EF BE 9D     FF 9D
10384       UGARITIC LETTER DELTA        F0 90 8E 84  D8 00 DF 84
</pre><p>
          The two characters in the chart are in order by code point
          value because <code class="literal">0xff9d</code> &lt;
          <code class="literal">0x10384</code>. And they are in order by
          <code class="literal">utf8</code> value because <code class="literal">0xef</code>
          &lt; <code class="literal">0xf0</code>. But they are not in order by
          <code class="literal">utf16</code> value, if we use byte-by-byte
          comparison, because <code class="literal">0xff</code> &gt;
          <code class="literal">0xd8</code>.
        </p><p>
          So MySQL's <code class="literal">utf16_bin</code> collation is not
          <span class="quote">“<span class="quote">byte by byte.</span>”</span> It is <span class="quote">“<span class="quote">by code
          point.</span>”</span> When MySQL sees a supplementary-character
          encoding in <code class="literal">utf16</code>, it converts to the
          character's code-point value, and then compares. Therefore,
          <code class="literal">utf8_bin</code> and <code class="literal">utf16_bin</code>
          are the same ordering. This is consistent with the SQL:2008
          standard requirement for a UCS_BASIC collation:
          <span class="quote">“<span class="quote">UCS_BASIC is a collation in which the ordering is
          determined entirely by the Unicode scalar values of the
          characters in the strings being sorted. It is applicable to
          the UCS character repertoire. Since every character repertoire
          is a subset of the UCS repertoire, the UCS_BASIC collation is
          potentially applicable to every character set. NOTE 11: The
          Unicode scalar value of a character is its code point treated
          as an unsigned integer.</span>”</span>
        </p><p>
          If the character set is <code class="literal">ucs2</code>, comparison is
          byte-by-byte, but <code class="literal">ucs2</code> strings should not
          contain surrogates, anyway.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h4 class="title"><a name="charset-unicode-sets-miscellaneous"></a>Miscellaneous Information</h4>

</div>

</div>

</div>
<p>
          The
          <code class="literal"><em class="replaceable"><code>xxx</code></em>_general_mysql500_ci</code>
          collations preserve the pre-5.1.24 ordering of the original
          <code class="literal"><em class="replaceable"><code>xxx</code></em>_general_ci</code>
          collations and permit upgrades for tables created before MySQL
          5.1.24 (Bug #27877).
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="charset-we-sets"></a>10.10.2 West European Character Sets</h3>

</div>

</div>

</div>
<a class="indexterm" name="idm140091696190288"></a><a class="indexterm" name="idm140091696188832"></a><p>
        Western European character sets cover most West European
        languages, such as French, Spanish, Catalan, Basque, Portuguese,
        Italian, Albanian, Dutch, German, Danish, Swedish, Norwegian,
        Finnish, Faroese, Icelandic, Irish, Scottish, and English.
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            <code class="literal">ascii</code> (US ASCII) collations:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
                <code class="literal">ascii_bin</code>
              </p></li><li class="listitem"><p>
                <code class="literal">ascii_general_ci</code> (default)
</p></li></ul>
</div>
</li><li class="listitem"><p>
            <code class="literal">cp850</code> (DOS West European) collations:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
                <code class="literal">cp850_bin</code>
              </p></li><li class="listitem"><p>
                <code class="literal">cp850_general_ci</code> (default)
</p></li></ul>
</div>
</li><li class="listitem"><p>
            <code class="literal">dec8</code> (DEC Western European) collations:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
                <code class="literal">dec8_bin</code>
              </p></li><li class="listitem"><p>
                <code class="literal">dec8_swedish_ci</code> (default)
</p></li></ul>
</div>
</li><li class="listitem"><p>
            <code class="literal">hp8</code> (HP Western European) collations:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
                <code class="literal">hp8_bin</code>
              </p></li><li class="listitem"><p>
                <code class="literal">hp8_english_ci</code> (default)
</p></li></ul>
</div>
</li><li class="listitem"><p>
            <code class="literal">latin1</code> (cp1252 West European) collations:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
                <code class="literal">latin1_bin</code>
              </p></li><li class="listitem"><p>
                <code class="literal">latin1_danish_ci</code>
              </p></li><li class="listitem"><p>
                <code class="literal">latin1_general_ci</code>
              </p></li><li class="listitem"><p>
                <code class="literal">latin1_general_cs</code>
              </p></li><li class="listitem"><p>
                <code class="literal">latin1_german1_ci</code>
              </p></li><li class="listitem"><p>
                <code class="literal">latin1_german2_ci</code>
              </p></li><li class="listitem"><p>
                <code class="literal">latin1_spanish_ci</code>
              </p></li><li class="listitem"><p>
                <code class="literal">latin1_swedish_ci</code> (default)
</p></li></ul>
</div>
<p>
            MySQL's <code class="literal">latin1</code> is the same as the Windows
            <code class="literal">cp1252</code> character set. This means it is
            the same as the official <code class="literal">ISO 8859-1</code> or
            IANA (Internet Assigned Numbers Authority)
            <code class="literal">latin1</code>, except that IANA
            <code class="literal">latin1</code> treats the code points between
            <code class="literal">0x80</code> and <code class="literal">0x9f</code> as
            <span class="quote">“<span class="quote">undefined,</span>”</span> whereas <code class="literal">cp1252</code>,
            and therefore MySQL's <code class="literal">latin1</code>, assign
            characters for those positions. For example,
            <code class="literal">0x80</code> is the Euro sign. For the
            <span class="quote">“<span class="quote">undefined</span>”</span> entries in
            <code class="literal">cp1252</code>, MySQL translates
            <code class="literal">0x81</code> to Unicode
            <code class="literal">0x0081</code>, <code class="literal">0x8d</code> to
            <code class="literal">0x008d</code>, <code class="literal">0x8f</code> to
            <code class="literal">0x008f</code>, <code class="literal">0x90</code> to
            <code class="literal">0x0090</code>, and <code class="literal">0x9d</code> to
            <code class="literal">0x009d</code>.
          </p><p>
            The <code class="literal">latin1_swedish_ci</code> collation is the
            default that probably is used by the majority of MySQL
            customers. Although it is frequently said that it is based
            on the Swedish/Finnish collation rules, there are Swedes and
            Finns who disagree with this statement.
          </p><a class="indexterm" name="idm140091696135456"></a><a class="indexterm" name="idm140091696134368"></a><a class="indexterm" name="idm140091696133280"></a><a class="indexterm" name="idm140091696132192"></a><p>
            The <code class="literal">latin1_german1_ci</code> and
            <code class="literal">latin1_german2_ci</code> collations are based on
            the DIN-1 and DIN-2 standards, where DIN stands for
            <span class="emphasis"><em><span lang="de" class="phrase">Deutsches Institut für
            Normung</span></em></span> (the German equivalent of ANSI).
            DIN-1 is called the <span class="quote">“<span class="quote">dictionary collation</span>”</span> and
            DIN-2 is called the <span class="quote">“<span class="quote">phone book collation.</span>”</span> For
            an example of the effect this has in comparisons or when
            doing searches, see
            <a class="xref" href="charset.html#charset-collation-effect" title="10.8.6 Examples of the Effect of Collation">Section 10.8.6, “Examples of the Effect of Collation”</a>.
</p><a class="indexterm" name="idm140091696126432"></a><a class="indexterm" name="idm140091696125392"></a><a class="indexterm" name="idm140091696124304"></a><a class="indexterm" name="idm140091696123216"></a>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
                <code class="literal">latin1_german1_ci</code> (dictionary) rules:
              </p><pre data-lang="none" class="programlisting">
Ä = A
Ö = O
Ü = U
ß = s
</pre></li><li class="listitem"><p>
                <code class="literal">latin1_german2_ci</code> (phone-book) rules:
              </p><pre data-lang="none" class="programlisting">
Ä = AE
Ö = OE
Ü = UE
ß = ss
</pre></li></ul>
</div>
<p>
            In the <code class="literal">latin1_spanish_ci</code> collation,
            <code class="literal">ñ</code> (n-tilde) is a separate letter between
            <code class="literal">n</code> and <code class="literal">o</code>.
          </p></li><li class="listitem"><p>
            <code class="literal">macroman</code> (Mac West European) collations:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
                <code class="literal">macroman_bin</code>
              </p></li><li class="listitem"><p>
                <code class="literal">macroman_general_ci</code> (default)
</p></li></ul>
</div>
</li><li class="listitem"><p>
            <code class="literal">swe7</code> (7bit Swedish) collations:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
                <code class="literal">swe7_bin</code>
              </p></li><li class="listitem"><p>
                <code class="literal">swe7_swedish_ci</code> (default)
</p></li></ul>
</div>
</li></ul>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="charset-ce-sets"></a>10.10.3 Central European Character Sets</h3>

</div>

</div>

</div>
<a class="indexterm" name="idm140091696102144"></a><a class="indexterm" name="idm140091696100688"></a><p>
        MySQL provides some support for character sets used in the Czech
        Republic, Slovakia, Hungary, Romania, Slovenia, Croatia, Poland,
        and Serbia (Latin).
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            <code class="literal">cp1250</code> (Windows Central European)
            collations:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
                <code class="literal">cp1250_bin</code>
              </p></li><li class="listitem"><p>
                <code class="literal">cp1250_croatian_ci</code>
              </p></li><li class="listitem"><p>
                <code class="literal">cp1250_czech_cs</code>
              </p></li><li class="listitem"><p>
                <code class="literal">cp1250_general_ci</code> (default)
              </p></li><li class="listitem"><p>
                <code class="literal">cp1250_polish_ci</code>
</p></li></ul>
</div>
</li><li class="listitem"><p>
            <code class="literal">cp852</code> (DOS Central European) collations:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
                <code class="literal">cp852_bin</code>
              </p></li><li class="listitem"><p>
                <code class="literal">cp852_general_ci</code> (default)
</p></li></ul>
</div>
</li><li class="listitem"><p>
            <code class="literal">keybcs2</code> (DOS Kamenicky Czech-Slovak)
            collations:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
                <code class="literal">keybcs2_bin</code>
              </p></li><li class="listitem"><p>
                <code class="literal">keybcs2_general_ci</code> (default)
</p></li></ul>
</div>
</li><li class="listitem"><p>
            <code class="literal">latin2</code> (ISO 8859-2 Central European)
            collations:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
                <code class="literal">latin2_bin</code>
              </p></li><li class="listitem"><p>
                <code class="literal">latin2_croatian_ci</code>
              </p></li><li class="listitem"><p>
                <code class="literal">latin2_czech_cs</code>
              </p></li><li class="listitem"><p>
                <code class="literal">latin2_general_ci</code> (default)
              </p></li><li class="listitem"><p>
                <code class="literal">latin2_hungarian_ci</code>
</p></li></ul>
</div>
</li><li class="listitem"><p>
            <code class="literal">macce</code> (Mac Central European) collations:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
                <code class="literal">macce_bin</code>
              </p></li><li class="listitem"><p>
                <code class="literal">macce_general_ci</code> (default)
</p></li></ul>
</div>
</li></ul>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="charset-se-me-sets"></a>10.10.4 South European and Middle East Character Sets</h3>

</div>

</div>

</div>
<a class="indexterm" name="idm140091696063792"></a><a class="indexterm" name="idm140091696062336"></a><a class="indexterm" name="idm140091696060848"></a><a class="indexterm" name="idm140091696059360"></a><p>
        South European and Middle Eastern character sets supported by
        MySQL include Armenian, Arabic, Georgian, Greek, Hebrew, and
        Turkish.
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            <code class="literal">armscii8</code> (ARMSCII-8 Armenian) collations:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
                <code class="literal">armscii8_bin</code>
              </p></li><li class="listitem"><p>
                <code class="literal">armscii8_general_ci</code> (default)
</p></li></ul>
</div>
</li><li class="listitem"><p>
            <code class="literal">cp1256</code> (Windows Arabic) collations:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
                <code class="literal">cp1256_bin</code>
              </p></li><li class="listitem"><p>
                <code class="literal">cp1256_general_ci</code> (default)
</p></li></ul>
</div>
</li><li class="listitem"><p>
            <code class="literal">geostd8</code> (GEOSTD8 Georgian) collations:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
                <code class="literal">geostd8_bin</code>
              </p></li><li class="listitem"><p>
                <code class="literal">geostd8_general_ci</code> (default)
</p></li></ul>
</div>
</li><li class="listitem"><p>
            <code class="literal">greek</code> (ISO 8859-7 Greek) collations:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
                <code class="literal">greek_bin</code>
              </p></li><li class="listitem"><p>
                <code class="literal">greek_general_ci</code> (default)
</p></li></ul>
</div>
</li><li class="listitem"><p>
            <code class="literal">hebrew</code> (ISO 8859-8 Hebrew) collations:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
                <code class="literal">hebrew_bin</code>
              </p></li><li class="listitem"><p>
                <code class="literal">hebrew_general_ci</code> (default)
</p></li></ul>
</div>
</li><li class="listitem"><p>
            <code class="literal">latin5</code> (ISO 8859-9 Turkish) collations:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
                <code class="literal">latin5_bin</code>
              </p></li><li class="listitem"><p>
                <code class="literal">latin5_turkish_ci</code> (default)
</p></li></ul>
</div>
</li></ul>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="charset-baltic-sets"></a>10.10.5 Baltic Character Sets</h3>

</div>

</div>

</div>
<a class="indexterm" name="idm140091696026464"></a><a class="indexterm" name="idm140091696024976"></a><p>
        The Baltic character sets cover Estonian, Latvian, and
        Lithuanian languages.
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            <code class="literal">cp1257</code> (Windows Baltic) collations:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
                <code class="literal">cp1257_bin</code>
              </p></li><li class="listitem"><p>
                <code class="literal">cp1257_general_ci</code> (default)
              </p></li><li class="listitem"><p>
                <code class="literal">cp1257_lithuanian_ci</code>
</p></li></ul>
</div>
</li><li class="listitem"><p>
            <code class="literal">latin7</code> (ISO 8859-13 Baltic) collations:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
                <code class="literal">latin7_bin</code>
              </p></li><li class="listitem"><p>
                <code class="literal">latin7_estonian_cs</code>
              </p></li><li class="listitem"><p>
                <code class="literal">latin7_general_ci</code> (default)
              </p></li><li class="listitem"><p>
                <code class="literal">latin7_general_cs</code>
</p></li></ul>
</div>
</li></ul>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="charset-cyrillic-sets"></a>10.10.6 Cyrillic Character Sets</h3>

</div>

</div>

</div>
<a class="indexterm" name="idm140091696007296"></a><a class="indexterm" name="idm140091696005808"></a><p>
        The Cyrillic character sets and collations are for use with
        Belarusian, Bulgarian, Russian, Ukrainian, and Serbian
        (Cyrillic) languages.
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            <code class="literal">cp1251</code> (Windows Cyrillic) collations:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
                <code class="literal">cp1251_bin</code>
              </p></li><li class="listitem"><p>
                <code class="literal">cp1251_bulgarian_ci</code>
              </p></li><li class="listitem"><p>
                <code class="literal">cp1251_general_ci</code> (default)
              </p></li><li class="listitem"><p>
                <code class="literal">cp1251_general_cs</code>
              </p></li><li class="listitem"><p>
                <code class="literal">cp1251_ukrainian_ci</code>
</p></li></ul>
</div>
</li><li class="listitem"><p>
            <code class="literal">cp866</code> (DOS Russian) collations:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
                <code class="literal">cp866_bin</code>
              </p></li><li class="listitem"><p>
                <code class="literal">cp866_general_ci</code> (default)
</p></li></ul>
</div>
</li><li class="listitem"><p>
            <code class="literal">koi8r</code> (KOI8-R Relcom Russian) collations:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
                <code class="literal">koi8r_bin</code>
              </p></li><li class="listitem"><p>
                <code class="literal">koi8r_general_ci</code> (default)
</p></li></ul>
</div>
</li><li class="listitem"><p>
            <code class="literal">koi8u</code> (KOI8-U Ukrainian) collations:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
                <code class="literal">koi8u_bin</code>
              </p></li><li class="listitem"><p>
                <code class="literal">koi8u_general_ci</code> (default)
</p></li></ul>
</div>
</li></ul>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="charset-asian-sets"></a>10.10.7 Asian Character Sets</h3>

</div>

</div>

</div>
<div class="toc">
<dl class="toc"><dt><span class="section"><a href="charset.html#charset-cp932">10.10.7.1 The cp932 Character Set</a></span></dt><dt><span class="section"><a href="charset.html#charset-gb18030">10.10.7.2 The gb18030 Character Set</a></span></dt></dl>
</div>
<a class="indexterm" name="idm140091695977616"></a><a class="indexterm" name="idm140091695976128"></a><p>
        The Asian character sets that we support include Chinese,
        Japanese, Korean, and Thai. These can be complicated. For
        example, the Chinese sets must allow for thousands of different
        characters. See <a class="xref" href="charset.html#charset-cp932" title="10.10.7.1 The cp932 Character Set">Section 10.10.7.1, “The cp932 Character Set”</a>, for additional
        information about the <code class="literal">cp932</code> and
        <code class="literal">sjis</code> character sets. See
        <a class="xref" href="charset.html#charset-gb18030" title="10.10.7.2 The gb18030 Character Set">Section 10.10.7.2, “The gb18030 Character Set”</a>, for additional information
        about character set support for the Chinese National Standard GB
        18030.
      </p><p>
        For answers to some common questions and problems relating
        support for Asian character sets in MySQL, see
        <a class="xref" href="faqs.html#faqs-cjk" title="A.11 MySQL 8.0 FAQ: MySQL Chinese, Japanese, and Korean Character Sets">Section A.11, “MySQL 8.0 FAQ: MySQL Chinese, Japanese, and Korean
      Character Sets”</a>.
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            <code class="literal">big5</code> (Big5 Traditional Chinese)
            collations:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
                <code class="literal">big5_bin</code>
              </p></li><li class="listitem"><p>
                <code class="literal">big5_chinese_ci</code> (default)
</p></li></ul>
</div>
</li><li class="listitem"><p>
            <a class="link" href="charset.html#charset-cp932" title="10.10.7.1 The cp932 Character Set"><code class="literal">cp932</code></a>
            (SJIS for Windows Japanese) collations:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
                <code class="literal">cp932_bin</code>
              </p></li><li class="listitem"><p>
                <code class="literal">cp932_japanese_ci</code> (default)
</p></li></ul>
</div>
</li><li class="listitem"><p>
            <code class="literal">eucjpms</code> (UJIS for Windows Japanese)
            collations:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
                <code class="literal">eucjpms_bin</code>
              </p></li><li class="listitem"><p>
                <code class="literal">eucjpms_japanese_ci</code> (default)
</p></li></ul>
</div>
</li><li class="listitem"><p>
            <code class="literal">euckr</code> (EUC-KR Korean) collations:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
                <code class="literal">euckr_bin</code>
              </p></li><li class="listitem"><p>
                <code class="literal">euckr_korean_ci</code> (default)
</p></li></ul>
</div>
</li><li class="listitem"><p>
            <code class="literal">gb2312</code> (GB2312 Simplified Chinese)
            collations:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
                <code class="literal">gb2312_bin</code>
              </p></li><li class="listitem"><p>
                <code class="literal">gb2312_chinese_ci</code> (default)
</p></li></ul>
</div>
</li><li class="listitem"><p>
            <code class="literal">gbk</code> (GBK Simplified Chinese) collations:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
                <code class="literal">gbk_bin</code>
              </p></li><li class="listitem"><p>
                <code class="literal">gbk_chinese_ci</code> (default)
</p></li></ul>
</div>
</li><li class="listitem"><p>
            <a class="link" href="charset.html#charset-gb18030" title="10.10.7.2 The gb18030 Character Set"><code class="literal">gb18030</code></a>
            (China National Standard GB18030) collations:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
                <code class="literal">gb18030_bin</code>
              </p></li><li class="listitem"><p>
                <code class="literal">gb18030_chinese_ci</code> (default)
              </p></li><li class="listitem"><p>
                <code class="literal">gb18030_unicode_520_ci</code>
</p></li></ul>
</div>
</li><li class="listitem"><p>
            <code class="literal">sjis</code> (Shift-JIS Japanese) collations:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
                <code class="literal">sjis_bin</code>
              </p></li><li class="listitem"><p>
                <code class="literal">sjis_japanese_ci</code> (default)
</p></li></ul>
</div>
</li><li class="listitem"><p>
            <code class="literal">tis620</code> (TIS620 Thai) collations:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
                <code class="literal">tis620_bin</code>
              </p></li><li class="listitem"><p>
                <code class="literal">tis620_thai_ci</code> (default)
</p></li></ul>
</div>
</li><li class="listitem"><p>
            <code class="literal">ujis</code> (EUC-JP Japanese) collations:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
                <code class="literal">ujis_bin</code>
              </p></li><li class="listitem"><p>
                <code class="literal">ujis_japanese_ci</code> (default)
</p></li></ul>
</div>
</li></ul>
</div>
<p>
        The <code class="literal">big5_chinese_ci</code> collation sorts on number
        of strokes.
</p>
<div class="section">

<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="charset-cp932"></a>10.10.7.1 The cp932 Character Set</h4>
</div>
</div>
</div>
<p>
          <span class="bold"><strong>Why is <code class="literal">cp932</code>
          needed?</strong></span>
        </p><p>
          In MySQL, the <code class="literal">sjis</code> character set
          corresponds to the <code class="literal">Shift_JIS</code> character set
          defined by IANA, which supports JIS X0201 and JIS X0208
          characters. (See
          <a class="ulink" href="http://www.iana.org/assignments/character-sets" target="_top">http://www.iana.org/assignments/character-sets</a>.)
        </p><p>
          However, the meaning of <span class="quote">“<span class="quote">SHIFT JIS</span>”</span> as a
          descriptive term has become very vague and it often includes
          the extensions to <code class="literal">Shift_JIS</code> that are
          defined by various vendors.
        </p><p>
          For example, <span class="quote">“<span class="quote">SHIFT JIS</span>”</span> used in Japanese Windows
          environments is a Microsoft extension of
          <code class="literal">Shift_JIS</code> and its exact name is
          <code class="literal">Microsoft Windows Codepage : 932</code> or
          <code class="literal">cp932</code>. In addition to the characters
          supported by <code class="literal">Shift_JIS</code>,
          <code class="literal">cp932</code> supports extension characters such as
          NEC special characters, NEC selected—IBM extended
          characters, and IBM selected characters.
        </p><p>
          Many Japanese users have experienced problems using these
          extension characters. These problems stem from the following
          factors:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              MySQL automatically converts character sets.
            </p></li><li class="listitem"><p>
              Character sets are converted using Unicode
              (<code class="literal">ucs2</code>).
            </p></li><li class="listitem"><p>
              The <code class="literal">sjis</code> character set does not support
              the conversion of these extension characters.
            </p></li><li class="listitem"><p>
              There are several conversion rules from so-called
              <span class="quote">“<span class="quote">SHIFT JIS</span>”</span> to Unicode, and some characters
              are converted to Unicode differently depending on the
              conversion rule. MySQL supports only one of these rules
              (described later).
</p></li></ul>
</div>
<p>
          The MySQL <code class="literal">cp932</code> character set is designed
          to solve these problems.
        </p><p>
          Because MySQL supports character set conversion, it is
          important to separate IANA <code class="literal">Shift_JIS</code> and
          <code class="literal">cp932</code> into two different character sets
          because they provide different conversion rules.
        </p><p>
          <span class="bold"><strong>How does <code class="literal">cp932</code> differ
          from <code class="literal">sjis</code>?</strong></span>
        </p><p>
          The <code class="literal">cp932</code> character set differs from
          <code class="literal">sjis</code> in the following ways:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              <code class="literal">cp932</code> supports NEC special characters,
              NEC selected—IBM extended characters, and IBM
              selected characters.
            </p></li><li class="listitem"><p>
              Some <code class="literal">cp932</code> characters have two
              different code points, both of which convert to the same
              Unicode code point. When converting from Unicode back to
              <code class="literal">cp932</code>, one of the code points must be
              selected. For this <span class="quote">“<span class="quote">round trip conversion,</span>”</span>
              the rule recommended by Microsoft is used. (See
              <a class="ulink" href="http://support.microsoft.com/kb/170559/EN-US/" target="_top">http://support.microsoft.com/kb/170559/EN-US/</a>.)
            </p><p>
              The conversion rule works like this:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
                  If the character is in both JIS X 0208 and NEC special
                  characters, use the code point of JIS X 0208.
                </p></li><li class="listitem"><p>
                  If the character is in both NEC special characters and
                  IBM selected characters, use the code point of NEC
                  special characters.
                </p></li><li class="listitem"><p>
                  If the character is in both IBM selected characters
                  and NEC selected—IBM extended characters, use
                  the code point of IBM extended characters.
</p></li></ul>
</div>
<p>
              The table shown at
              <a class="ulink" href="https://msdn.microsoft.com/en-us/goglobal/cc305152.aspx" target="_top">https://msdn.microsoft.com/en-us/goglobal/cc305152.aspx</a>
              provides information about the Unicode values of
              <code class="literal">cp932</code> characters. For
              <code class="literal">cp932</code> table entries with characters
              under which a four-digit number appears, the number
              represents the corresponding Unicode
              (<code class="literal">ucs2</code>) encoding. For table entries with
              an underlined two-digit value appears, there is a range of
              <code class="literal">cp932</code> character values that begin with
              those two digits. Clicking such a table entry takes you to
              a page that displays the Unicode value for each of the
              <code class="literal">cp932</code> characters that begin with those
              digits.
            </p><p>
              The following links are of special interest. They
              correspond to the encodings for the following sets of
              characters:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
                  NEC special characters (lead byte
                  <code class="literal">0x87</code>):
                </p><pre data-lang="html" class="programlisting">
<a class="ulink" href="https://msdn.microsoft.com/en-us/goglobal/gg674964" target="_top">https://msdn.microsoft.com/en-us/goglobal/gg674964</a>
</pre></li><li class="listitem"><p>
                  NEC selected—IBM extended characters (lead byte
                  <code class="literal">0xED</code> and <code class="literal">0xEE</code>):
                </p><pre data-lang="html" class="programlisting">
<a class="ulink" href="https://msdn.microsoft.com/en-us/goglobal/gg671837" target="_top">https://msdn.microsoft.com/en-us/goglobal/gg671837</a>
<a class="ulink" href="https://msdn.microsoft.com/en-us/goglobal/gg671838" target="_top">https://msdn.microsoft.com/en-us/goglobal/gg671838</a>
</pre></li><li class="listitem"><p>
                  IBM selected characters (lead byte
                  <code class="literal">0xFA</code>, <code class="literal">0xFB</code>,
                  <code class="literal">0xFC</code>):
                </p><pre data-lang="html" class="programlisting">
<a class="ulink" href="https://msdn.microsoft.com/en-us/goglobal/gg671839" target="_top">https://msdn.microsoft.com/en-us/goglobal/gg671839</a>
<a class="ulink" href="https://msdn.microsoft.com/en-us/goglobal/gg671840" target="_top">https://msdn.microsoft.com/en-us/goglobal/gg671840</a>
<a class="ulink" href="https://msdn.microsoft.com/en-us/goglobal/gg671841" target="_top">https://msdn.microsoft.com/en-us/goglobal/gg671841</a>
</pre></li></ul>
</div>
</li><li class="listitem"><p>
              <code class="literal">cp932</code> supports conversion of
              user-defined characters in combination with
              <code class="literal">eucjpms</code>, and solves the problems with
              <code class="literal">sjis</code>/<code class="literal">ujis</code>
              conversion. For details, please refer to
              <a class="ulink" href="http://www.sljfaq.org/afaq/encodings.html" target="_top">http://www.sljfaq.org/afaq/encodings.html</a>.
</p></li></ul>
</div>
<p>
          For some characters, conversion to and from
          <code class="literal">ucs2</code> is different for
          <code class="literal">sjis</code> and <code class="literal">cp932</code>. The
          following tables illustrate these differences.
        </p><p>
          Conversion to <code class="literal">ucs2</code>:
</p>
<div class="informaltable">
<table summary="sjis/cp932 values and the difference between sjis to ucs2 conversion and cp932 to ucs2 conversion."><col width="33%"><col width="33%"><col width="33%"><thead><tr>
              <th scope="col"><code class="literal">sjis</code>/<code class="literal">cp932</code> Value</th>
              <th scope="col"><code class="literal">sjis</code> -&gt; <code class="literal">ucs2</code> Conversion</th>
              <th scope="col"><code class="literal">cp932</code> -&gt; <code class="literal">ucs2</code> Conversion</th>
            </tr></thead><tbody><tr>
              <td scope="row">5C</td>
              <td>005C</td>
              <td>005C</td>
            </tr><tr>
              <td scope="row">7E</td>
              <td>007E</td>
              <td>007E</td>
            </tr><tr>
              <td scope="row">815C</td>
              <td>2015</td>
              <td>2015</td>
            </tr><tr>
              <td scope="row">815F</td>
              <td>005C</td>
              <td>FF3C</td>
            </tr><tr>
              <td scope="row">8160</td>
              <td>301C</td>
              <td>FF5E</td>
            </tr><tr>
              <td scope="row">8161</td>
              <td>2016</td>
              <td>2225</td>
            </tr><tr>
              <td scope="row">817C</td>
              <td>2212</td>
              <td>FF0D</td>
            </tr><tr>
              <td scope="row">8191</td>
              <td>00A2</td>
              <td>FFE0</td>
            </tr><tr>
              <td scope="row">8192</td>
              <td>00A3</td>
              <td>FFE1</td>
            </tr><tr>
              <td scope="row">81CA</td>
              <td>00AC</td>
              <td>FFE2</td>
</tr></tbody></table>
</div>
<p>
          Conversion from <code class="literal">ucs2</code>:
</p>
<div class="informaltable">
<table summary="ucs2 values and the difference between ucs2 to sjis conversion and ucs2 to cp932 conversion."><col width="33%"><col width="33%"><col width="33%"><thead><tr>
              <th scope="col"><code class="literal">ucs2</code> value</th>
              <th scope="col"><code class="literal">ucs2</code> -&gt; <code class="literal">sjis</code> Conversion</th>
              <th scope="col"><code class="literal">ucs2</code> -&gt; <code class="literal">cp932</code> Conversion</th>
            </tr></thead><tbody><tr>
              <td scope="row">005C</td>
              <td>815F</td>
              <td>5C</td>
            </tr><tr>
              <td scope="row">007E</td>
              <td>7E</td>
              <td>7E</td>
            </tr><tr>
              <td scope="row">00A2</td>
              <td>8191</td>
              <td>3F</td>
            </tr><tr>
              <td scope="row">00A3</td>
              <td>8192</td>
              <td>3F</td>
            </tr><tr>
              <td scope="row">00AC</td>
              <td>81CA</td>
              <td>3F</td>
            </tr><tr>
              <td scope="row">2015</td>
              <td>815C</td>
              <td>815C</td>
            </tr><tr>
              <td scope="row">2016</td>
              <td>8161</td>
              <td>3F</td>
            </tr><tr>
              <td scope="row">2212</td>
              <td>817C</td>
              <td>3F</td>
            </tr><tr>
              <td scope="row">2225</td>
              <td>3F</td>
              <td>8161</td>
            </tr><tr>
              <td scope="row">301C</td>
              <td>8160</td>
              <td>3F</td>
            </tr><tr>
              <td scope="row">FF0D</td>
              <td>3F</td>
              <td>817C</td>
            </tr><tr>
              <td scope="row">FF3C</td>
              <td>3F</td>
              <td>815F</td>
            </tr><tr>
              <td scope="row">FF5E</td>
              <td>3F</td>
              <td>8160</td>
            </tr><tr>
              <td scope="row">FFE0</td>
              <td>3F</td>
              <td>8191</td>
            </tr><tr>
              <td scope="row">FFE1</td>
              <td>3F</td>
              <td>8192</td>
            </tr><tr>
              <td scope="row">FFE2</td>
              <td>3F</td>
              <td>81CA</td>
</tr></tbody></table>
</div>
<p>
          Users of any Japanese character sets should be aware that
          using
          <a class="link" href="server-administration.html#option_mysqld_character-set-client-handshake"><code class="option">--character-set-client-handshake</code></a>
          (or
          <a class="link" href="server-administration.html#option_mysqld_character-set-client-handshake"><code class="option">--skip-character-set-client-handshake</code></a>)
          has an important effect. See <a class="xref" href="server-administration.html#server-options" title="5.1.7 Server Command Options">Section 5.1.7, “Server Command Options”</a>.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="charset-gb18030"></a>10.10.7.2 The gb18030 Character Set</h4>

</div>

</div>

</div>
<p>
          In MySQL, the <code class="literal">gb18030</code> character set
          corresponds to the <span class="quote">“<span class="quote">Chinese National Standard GB
          18030-2005: Information technology — Chinese coded
          character set</span>”</span>, which is the official character set of
          the People's Republic of China (PRC).
</p>
<h5><a name="idm140091695738240"></a>Characteristics of the MySQL gb18030 Character Set</h5>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              Supports all code points defined by the GB 18030-2005
              standard. Unassigned code points in the ranges
              (GB+8431A439, GB+90308130) and (GB+E3329A36, GB+EF39EF39)
              are treated as '<code class="literal">?</code>' (0x3F). Conversion
              of unassigned code points return '<code class="literal">?</code>'.
            </p></li><li class="listitem"><p>
              Supports UPPER and LOWER conversion for all GB18030 code
              points. Case folding defined by Unicode is also supported
              (based on <code class="filename">CaseFolding-6.3.0.txt</code>).
            </p></li><li class="listitem"><p>
              Supports Conversion of data to and from other character
              sets.
            </p></li><li class="listitem"><p>
              Supports SQL statements such as <a class="link" href="sql-syntax.html#set-names" title="13.7.5.3 SET NAMES Syntax"><code class="literal">SET
              NAMES</code></a>.
            </p></li><li class="listitem"><p>
              Supports comparison between <code class="literal">gb18030</code>
              strings, and between <code class="literal">gb18030</code> strings
              and strings of other character sets. There is a conversion
              if strings have different character sets. Comparisons that
              include or ignore trailing spaces are also supported.
            </p></li><li class="listitem"><p>
              The private use area (U+E000, U+F8FF) in Unicode is mapped
              to <code class="literal">gb18030</code>.
            </p></li><li class="listitem"><p>
              There is no mapping between (U+D800, U+DFFF) and GB18030.
              Attempted conversion of code points in this range returns
              '<code class="literal">?</code>'.
            </p></li><li class="listitem"><p>
              If an incoming sequence is illegal, an error or warning is
              returned. If an illegal sequence is used in
              <code class="literal">CONVERT()</code>, an error is returned.
              Otherwise, a warning is returned.
            </p></li><li class="listitem"><p>
              For consistency with <code class="literal">utf8</code> and
              <code class="literal">utf8mb4</code>, UPPER is not supported for
              ligatures.
            </p></li><li class="listitem"><p>
              Searches for ligatures also match uppercase ligatures when
              using the <code class="literal">gb18030_unicode_520_ci</code>
              collation.
            </p></li><li class="listitem"><p>
              If a character has more than one uppercase character, the
              chosen uppercase character is the one whose lowercase is
              the character itself.
            </p></li><li class="listitem"><p>
              The minimum multibyte length is 1 and the maximum is 4.
              The character set determines the length of a sequence
              using the first 1 or 2 bytes.
</p></li></ul>
</div>
<h5><a name="idm140091695716704"></a>Supported Collations</h5>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              <code class="literal">gb18030_bin</code>: A binary collation.
            </p></li><li class="listitem"><p>
              <code class="literal">gb18030_chinese_ci</code>: The default
              collation, which supports Pinyin. Sorting of non-Chinese
              characters is based on the order of the original sort key.
              The original sort key is <code class="literal">GB(UPPER(ch))</code>
              if <code class="literal">UPPER(ch)</code> exists. Otherwise, the
              original sort key is <code class="literal">GB(ch)</code>. Chinese
              characters are sorted according to the Pinyin collation
              defined in the Unicode Common Locale Data Repository (CLDR
              24). Non-Chinese characters are sorted before Chinese
              characters with the exception of
              <code class="literal">GB+FE39FE39</code>, which is the code point
              maximum.
            </p></li><li class="listitem"><p>
              <code class="literal">gb18030_unicode_520_ci</code>: A Unicode
              collation. Use this collation if you need to ensure that
              ligatures are sorted correctly.
</p></li></ul>
</div>

</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="charset-binary-set"></a>10.10.8 The Binary Character Set</h3>

</div>

</div>

</div>
<a class="indexterm" name="idm140091695706208"></a><a class="indexterm" name="idm140091695704752"></a><p>
        The <code class="literal">binary</code> character set is the chararcter
        set of binary strings, which are sequences of bytes. The
        <code class="literal">binary</code> character set has one collation, also
        named <code class="literal">binary</code>. Comparison and sorting are
        based on numeric byte values. The effect is that lettercase and
        accent differences are significant in comparisons. That is, the
        <code class="literal">binary</code> collation is case-sensitive and accent
        sensitive.
      </p><pre data-lang="sql" class="programlisting">
mysql&gt; <strong class="userinput"><code>SET NAMES 'binary';</code></strong>
mysql&gt; <strong class="userinput"><code>SELECT CHARSET('abc'), COLLATION('abc');</code></strong>
+----------------+------------------+
| CHARSET('abc') | COLLATION('abc') |
+----------------+------------------+
| binary         | binary           |
+----------------+------------------+
mysql&gt; <strong class="userinput"><code>SELECT 'abc' = 'ABC', 'a' = 'ä';</code></strong>
+---------------+------------+
| 'abc' = 'ABC' | 'a' = 'ä'  |
+---------------+------------+
|             0 |          0 |
+---------------+------------+
</pre><p>
        For information about the differences between the
        <code class="literal">binary</code> collation of the
        <code class="literal">binary</code> character set and the
        <code class="literal">_bin</code> collations of nonbinary character sets,
        see <a class="xref" href="charset.html#charset-binary-collations" title="10.8.5 The binary Collation Compared to _bin Collations">Section 10.8.5, “The binary Collation Compared to _bin Collations”</a>.
      </p><p>
        To convert a string expression to a binary string, any of these
        constructs are equivalent:
      </p><pre data-lang="sql" class="programlisting">
BINARY <em class="replaceable"><code>expr</code></em>
CAST(<em class="replaceable"><code>expr</code></em> AS BINARY)
CONVERT(<em class="replaceable"><code>expr</code></em> USING BINARY)
</pre><a class="indexterm" name="idm140091695689552"></a><p>
        If <em class="replaceable"><code>expr</code></em> is a character string
        literal, the <code class="literal">_binary</code> introducer may be used
        to designate it as a binary string. For example:
      </p><pre data-lang="sql" class="programlisting">
_binary 'a'
</pre><p>
        The <code class="literal">_binary</code> introducer is permitted for
        hexadecimal literals and bit-value literals as well, but
        unnecessary; such literals are binary strings by default.
      </p><p>
        For more information about introducers, see
        <a class="xref" href="charset.html#charset-introducer" title="10.3.8 Character Set Introducers">Section 10.3.8, “Character Set Introducers”</a>.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both"><a name="error-message-language"></a>10.11 Setting the Error Message Language</h2>

</div>

</div>

</div>
<a class="indexterm" name="idm140091695681680"></a><a class="indexterm" name="idm140091695680224"></a><a class="indexterm" name="idm140091695678736"></a><a class="indexterm" name="idm140091695677248"></a><p>
      By default, <a class="link" href="programs.html#mysqld" title="4.3.1 mysqld — The MySQL Server"><span class="command"><strong>mysqld</strong></span></a> produces error messages in
      English, but they can be displayed instead in any of several other
      languages: Czech, Danish, Dutch, Estonian, French, German, Greek,
      Hungarian, Italian, Japanese, Korean, Norwegian, Norwegian-ny,
      Polish, Portuguese, Romanian, Russian, Slovak, Spanish, or
      Swedish. This applies to messages the server writes to the error
      log and sends to clients.
    </p><p>
      To select the language in which the server writes error messages,
      follow the instructions in this section. For information about
      changing the character set for error messages (rather than the
      language), see <a class="xref" href="charset.html#charset-errors" title="10.6 Error Message Character Set">Section 10.6, “Error Message Character Set”</a>. For general
      information about configuring error logging, see
      <a class="xref" href="server-administration.html#error-log" title="5.4.2 The Error Log">Section 5.4.2, “The Error Log”</a>.
    </p><p>
      The server searches for the error message file using these rules:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          It looks for the file in a directory constructed from two
          system variable values,
          <a class="link" href="server-administration.html#sysvar_lc_messages_dir"><code class="literal">lc_messages_dir</code></a> and
          <a class="link" href="server-administration.html#sysvar_lc_messages"><code class="literal">lc_messages</code></a>, with the latter
          converted to a language name. Suppose that you start the
          server using this command:
        </p><pre data-lang="terminal" class="programlisting">
mysqld --lc_messages_dir=/usr/share/mysql --lc_messages=fr_FR
</pre><p>
          In this case, <a class="link" href="programs.html#mysqld" title="4.3.1 mysqld — The MySQL Server"><span class="command"><strong>mysqld</strong></span></a> maps the locale
          <code class="literal">fr_FR</code> to the language
          <code class="literal">french</code> and looks for the error file in the
          <code class="filename">/usr/share/mysql/french</code> directory.
        </p><p>
          By default, the language files are located in the
          <code class="filename">share/mysql/<em class="replaceable"><code>LANGUAGE</code></em></code>
          directory under the MySQL base directory.
        </p></li><li class="listitem"><p>
          If the message file cannot be found in the directory
          constructed as just described, the server ignores the
          <a class="link" href="server-administration.html#sysvar_lc_messages"><code class="literal">lc_messages</code></a> value and uses
          only the <a class="link" href="server-administration.html#sysvar_lc_messages_dir"><code class="literal">lc_messages_dir</code></a>
          value as the location in which to look.
        </p></li><li class="listitem"><p>
          If the server cannot find the configured message file, it
          writes a message to the error log to indicate the problem and
          defaults to built-in English messages.
</p></li></ul>
</div>
<p>
      The <a class="link" href="server-administration.html#sysvar_lc_messages_dir"><code class="literal">lc_messages_dir</code></a> system
      variable can be set only at server startup and has only a global
      read-only value at runtime.
      <a class="link" href="server-administration.html#sysvar_lc_messages"><code class="literal">lc_messages</code></a> can be set at server
      startup and has global and session values that can be modified at
      runtime. Thus, the error message language can be changed while the
      server is running, and each client can have its own error message
      language by setting its session
      <a class="link" href="server-administration.html#sysvar_lc_messages"><code class="literal">lc_messages</code></a> value to the desired
      locale name. For example, if the server is using the
      <code class="literal">fr_FR</code> locale for error messages, a client can
      execute this statement to receive error messages in English:
    </p><pre data-lang="sql" class="programlisting">
SET lc_messages = 'en_US';
</pre>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both"><a name="adding-character-set"></a>10.12 Adding a Character Set</h2>

</div>

</div>

</div>
<div class="toc">
<dl class="toc"><dt><span class="section"><a href="charset.html#character-arrays">10.12.1 Character Definition Arrays</a></span></dt><dt><span class="section"><a href="charset.html#string-collating">10.12.2 String Collating Support for Complex Character Sets</a></span></dt><dt><span class="section"><a href="charset.html#multibyte-characters">10.12.3 Multi-Byte Character Support for Complex Character Sets</a></span></dt></dl>
</div>
<a class="indexterm" name="idm140091695648896"></a><a class="indexterm" name="idm140091695647408"></a><p>
      This section discusses the procedure for adding a character set to
      MySQL. The proper procedure depends on whether the character set
      is simple or complex:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          If the character set does not need special string collating
          routines for sorting and does not need multibyte character
          support, it is simple.
        </p></li><li class="listitem"><p>
          If the character set needs either of those features, it is
          complex.
</p></li></ul>
</div>
<p>
      For example, <code class="literal">greek</code> and <code class="literal">swe7</code>
      are simple character sets, whereas <code class="literal">big5</code> and
      <code class="literal">czech</code> are complex character sets.
    </p><p>
      To use the following instructions, you must have a MySQL source
      distribution. In the instructions,
      <em class="replaceable"><code>MYSET</code></em> represents the name of the
      character set that you want to add.
</p>
<div class="orderedlist">
<ol class="orderedlist" type="1"><li class="listitem"><p>
          Add a <code class="literal">&lt;charset&gt;</code> element for
          <em class="replaceable"><code>MYSET</code></em> to the
          <code class="filename">sql/share/charsets/Index.xml</code> file. Use
          the existing contents in the file as a guide to adding new
          contents. A partial listing for the <code class="literal">latin1</code>
          <code class="literal">&lt;charset&gt;</code> element follows:
        </p><pre data-lang="xml" class="programlisting">
&lt;charset name="latin1"&gt;
  &lt;family&gt;Western&lt;/family&gt;
  &lt;description&gt;cp1252 West European&lt;/description&gt;
  ...
  &lt;collation name="latin1_swedish_ci" id="8" order="Finnish, Swedish"&gt;
    &lt;flag&gt;primary&lt;/flag&gt;
    &lt;flag&gt;compiled&lt;/flag&gt;
  &lt;/collation&gt;
  &lt;collation name="latin1_danish_ci" id="15" order="Danish"/&gt;
  ...
  &lt;collation name="latin1_bin" id="47" order="Binary"&gt;
    &lt;flag&gt;binary&lt;/flag&gt;
    &lt;flag&gt;compiled&lt;/flag&gt;
  &lt;/collation&gt;
  ...
&lt;/charset&gt;
</pre><p>
          The <code class="literal">&lt;charset&gt;</code> element must list all
          the collations for the character set. These must include at
          least a binary collation and a default (primary) collation.
          The default collation is often named using a suffix of
          <code class="literal">general_ci</code> (general, case insensitive). It
          is possible for the binary collation to be the default
          collation, but usually they are different. The default
          collation should have a <code class="literal">primary</code> flag. The
          binary collation should have a <code class="literal">binary</code> flag.
        </p><p>
          You must assign a unique ID number to each collation. The
          range of IDs from 1024 to 2047 is reserved for user-defined
          collations. To find the maximum of the currently used
          collation IDs, use this query:
        </p><pre data-lang="sql" class="programlisting">
SELECT MAX(ID) FROM INFORMATION_SCHEMA.COLLATIONS;
</pre></li><li class="listitem"><p>
          This step depends on whether you are adding a simple or
          complex character set. A simple character set requires only a
          configuration file, whereas a complex character set requires C
          source file that defines collation functions, multibyte
          functions, or both.
        </p><p>
          For a simple character set, create a configuration file,
          <code class="filename"><em class="replaceable"><code>MYSET</code></em>.xml</code>,
          that describes the character set properties. Create this file
          in the <code class="filename">sql/share/charsets</code> directory. You
          can use a copy of <code class="filename">latin1.xml</code> as the basis
          for this file. The syntax for the file is very simple:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              Comments are written as ordinary XML comments
              (<code class="literal">&lt;!-- <em class="replaceable"><code>text</code></em>
              --&gt;</code>).
            </p></li><li class="listitem"><p>
              Words within <code class="literal">&lt;map&gt;</code> array elements
              are separated by arbitrary amounts of whitespace.
            </p></li><li class="listitem"><p>
              Each word within <code class="literal">&lt;map&gt;</code> array
              elements must be a number in hexadecimal format.
            </p></li><li class="listitem"><p>
              The <code class="literal">&lt;map&gt;</code> array element for the
              <code class="literal">&lt;ctype&gt;</code> element has 257 words.
              The other <code class="literal">&lt;map&gt;</code> array elements
              after that have 256 words. See
              <a class="xref" href="charset.html#character-arrays" title="10.12.1 Character Definition Arrays">Section 10.12.1, “Character Definition Arrays”</a>.
            </p></li><li class="listitem"><p>
              For each collation listed in the
              <code class="literal">&lt;charset&gt;</code> element for the
              character set in <code class="filename">Index.xml</code>,
              <code class="filename"><em class="replaceable"><code>MYSET</code></em>.xml</code>
              must contain a <code class="literal">&lt;collation&gt;</code>
              element that defines the character ordering.
</p></li></ul>
</div>
<p>
          For a complex character set, create a C source file that
          describes the character set properties and defines the support
          routines necessary to properly perform operations on the
          character set:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              Create the file
              <code class="filename">ctype-<em class="replaceable"><code>MYSET</code></em>.c</code>
              in the <code class="filename">strings</code> directory. Look at one
              of the existing <code class="filename">ctype-*.c</code> files (such
              as <code class="filename">ctype-big5.c</code>) to see what needs to
              be defined. The arrays in your file must have names like
              <code class="literal">ctype_<em class="replaceable"><code>MYSET</code></em></code>,
              <code class="literal">to_lower_<em class="replaceable"><code>MYSET</code></em></code>,
              and so on. These correspond to the arrays for a simple
              character set. See <a class="xref" href="charset.html#character-arrays" title="10.12.1 Character Definition Arrays">Section 10.12.1, “Character Definition Arrays”</a>.
            </p></li><li class="listitem"><p>
              For each <code class="literal">&lt;collation&gt;</code> element
              listed in the <code class="literal">&lt;charset&gt;</code> element
              for the character set in <code class="filename">Index.xml</code>,
              the
              <code class="filename">ctype-<em class="replaceable"><code>MYSET</code></em>.c</code>
              file must provide an implementation of the collation.
            </p></li><li class="listitem"><p>
              If the character set requires string collating functions,
              see <a class="xref" href="charset.html#string-collating" title="10.12.2 String Collating Support for Complex Character Sets">Section 10.12.2, “String Collating Support for Complex Character Sets”</a>.
            </p></li><li class="listitem"><p>
              If the character set requires multibyte character support,
              see <a class="xref" href="charset.html#multibyte-characters" title="10.12.3 Multi-Byte Character Support for Complex Character Sets">Section 10.12.3, “Multi-Byte Character Support for Complex Character Sets”</a>.
</p></li></ul>
</div>
</li><li class="listitem"><p>
          Modify the configuration information. Use the existing
          configuration information as a guide to adding information for
          <em class="replaceable"><code>MYSYS</code></em>. The example here assumes
          that the character set has default and binary collations, but
          more lines are needed if <em class="replaceable"><code>MYSET</code></em> has
          additional collations.
</p>
<div class="orderedlist">
<ol class="orderedlist" type="a"><li class="listitem"><p>
              Edit <code class="filename">mysys/charset-def.c</code>, and
              <span class="quote">“<span class="quote">register</span>”</span> the collations for the new
              character set.
            </p><p>
              Add these lines to the <span class="quote">“<span class="quote">declaration</span>”</span> section:
            </p><pre data-lang="c" class="programlisting">
#ifdef HAVE_CHARSET_<em class="replaceable"><code>MYSET</code></em>
extern CHARSET_INFO my_charset_<em class="replaceable"><code>MYSET</code></em>_general_ci;
extern CHARSET_INFO my_charset_<em class="replaceable"><code>MYSET</code></em>_bin;
#endif
</pre><p>
              Add these lines to the <span class="quote">“<span class="quote">registration</span>”</span>
              section:
            </p><pre data-lang="c" class="programlisting">
#ifdef HAVE_CHARSET_<em class="replaceable"><code>MYSET</code></em>
  add_compiled_collation(&amp;my_charset_<em class="replaceable"><code>MYSET</code></em>_general_ci);
  add_compiled_collation(&amp;my_charset_<em class="replaceable"><code>MYSET</code></em>_bin);
#endif
</pre></li><li class="listitem"><p>
              If the character set uses
              <code class="filename">ctype-<em class="replaceable"><code>MYSET</code></em>.c</code>,
              edit <code class="filename">strings/CMakeLists.txt</code> and add
              <code class="filename">ctype-<em class="replaceable"><code>MYSET</code></em>.c</code>
              to the definition of the
              <code class="literal">STRINGS_SOURCES</code> variable.
            </p></li><li class="listitem"><p>
              Edit <code class="filename">cmake/character_sets.cmake</code>:
</p>
<div class="orderedlist">
<ol class="orderedlist" type="i"><li class="listitem"><p>
                  Add <em class="replaceable"><code>MYSET</code></em> to the value of
                  with <code class="literal">CHARSETS_AVAILABLE</code> in
                  alphabetic order.
                </p></li><li class="listitem"><p>
                  Add <em class="replaceable"><code>MYSET</code></em> to the value of
                  <code class="literal">CHARSETS_COMPLEX</code> in alphabetic
                  order. This is needed even for simple character sets,
                  or <span class="command"><strong>CMake</strong></span> will not recognize
                  <a class="link" href="installing.html#option_cmake_default_charset"><code class="option">-DDEFAULT_CHARSET=<em class="replaceable"><code>MYSET</code></em></code></a>.
</p></li></ol>
</div>
</li></ol>
</div>
</li><li class="listitem"><p>
          Reconfigure, recompile, and test.
</p></li></ol>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="character-arrays"></a>10.12.1 Character Definition Arrays</h3>

</div>

</div>

</div>
<p>
        Each simple character set has a configuration file located in
        the <code class="filename">sql/share/charsets</code> directory. For a
        character set named <em class="replaceable"><code>MYSYS</code></em>, the file
        is named
        <code class="filename"><em class="replaceable"><code>MYSET</code></em>.xml</code>. It
        uses <code class="literal">&lt;map&gt;</code> array elements to list
        character set properties. <code class="literal">&lt;map&gt;</code>
        elements appear within these elements:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            <code class="literal">&lt;ctype&gt;</code> defines attributes for each
            character.
          </p></li><li class="listitem"><p>
            <code class="literal">&lt;lower&gt;</code> and
            <code class="literal">&lt;upper&gt;</code> list the lowercase and
            uppercase characters.
          </p></li><li class="listitem"><p>
            <code class="literal">&lt;unicode&gt;</code> maps 8-bit character
            values to Unicode values.
          </p></li><li class="listitem"><p>
            <code class="literal">&lt;collation&gt;</code> elements indicate
            character ordering for comparison and sorting, one element
            per collation. Binary collations need no
            <code class="literal">&lt;map&gt;</code> element because the character
            codes themselves provide the ordering.
</p></li></ul>
</div>
<p>
        For a complex character set as implemented in a
        <code class="filename">ctype-<em class="replaceable"><code>MYSET</code></em>.c</code>
        file in the <code class="filename">strings</code> directory, there are
        corresponding arrays:
        <code class="literal">ctype_<em class="replaceable"><code>MYSET</code></em>[]</code>,
        <code class="literal">to_lower_<em class="replaceable"><code>MYSET</code></em>[]</code>,
        and so forth. Not every complex character set has all of the
        arrays. See also the existing <code class="filename">ctype-*.c</code>
        files for examples. See the
        <code class="filename">CHARSET_INFO.txt</code> file in the
        <code class="filename">strings</code> directory for additional
        information.
      </p><p>
        Most of the arrays are indexed by character value and have 256
        elements. The <code class="literal">&lt;ctype&gt;</code> array is indexed
        by character value + 1 and has 257 elements. This is a legacy
        convention for handling <code class="literal">EOF</code>.
      </p><p>
        <code class="literal">&lt;ctype&gt;</code> array elements are bit values.
        Each element describes the attributes of a single character in
        the character set. Each attribute is associated with a bitmask,
        as defined in <code class="filename">include/m_ctype.h</code>:
      </p><pre data-lang="c" class="programlisting">
#define _MY_U   01      /* Upper case */
#define _MY_L   02      /* Lower case */
#define _MY_NMR 04      /* Numeral (digit) */
#define _MY_SPC 010     /* Spacing character */
#define _MY_PNT 020     /* Punctuation */
#define _MY_CTR 040     /* Control character */
#define _MY_B   0100    /* Blank */
#define _MY_X   0200    /* heXadecimal digit */
</pre><p>
        The <code class="literal">&lt;ctype&gt;</code> value for a given character
        should be the union of the applicable bitmask values that
        describe the character. For example, <code class="literal">'A'</code> is
        an uppercase character (<code class="literal">_MY_U</code>) as well as a
        hexadecimal digit (<code class="literal">_MY_X</code>), so its
        <code class="literal">ctype</code> value should be defined like this:
      </p><pre data-lang="c" class="programlisting">
ctype['A'+1] = _MY_U | _MY_X = 01 | 0200 = 0201
</pre><p>
        The bitmask values in <code class="filename">m_ctype.h</code> are octal
        values, but the elements of the <code class="literal">&lt;ctype&gt;</code>
        array in
        <code class="filename"><em class="replaceable"><code>MYSET</code></em>.xml</code> should
        be written as hexadecimal values.
      </p><p>
        The <code class="literal">&lt;lower&gt;</code> and
        <code class="literal">&lt;upper&gt;</code> arrays hold the lowercase and
        uppercase characters corresponding to each member of the
        character set. For example:
      </p><pre data-lang="none" class="programlisting">
lower['A'] should contain 'a'
upper['a'] should contain 'A'
</pre><p>
        Each <code class="literal">&lt;collation&gt;</code> array indicates how
        characters should be ordered for comparison and sorting
        purposes. MySQL sorts characters based on the values of this
        information. In some cases, this is the same as the
        <code class="literal">&lt;upper&gt;</code> array, which means that sorting
        is case-insensitive. For more complicated sorting rules (for
        complex character sets), see the discussion of string collating
        in <a class="xref" href="charset.html#string-collating" title="10.12.2 String Collating Support for Complex Character Sets">Section 10.12.2, “String Collating Support for Complex Character Sets”</a>.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="string-collating"></a>10.12.2 String Collating Support for Complex Character Sets</h3>

</div>

</div>

</div>
<a class="indexterm" name="idm140091695526240"></a><a class="indexterm" name="idm140091695524784"></a><p>
        For a simple character set named
        <em class="replaceable"><code>MYSET</code></em>, sorting rules are specified in
        the <code class="filename"><em class="replaceable"><code>MYSET</code></em>.xml</code>
        configuration file using <code class="literal">&lt;map&gt;</code> array
        elements within <code class="literal">&lt;collation&gt;</code> elements.
        If the sorting rules for your language are too complex to be
        handled with simple arrays, you must define string collating
        functions in the
        <code class="filename">ctype-<em class="replaceable"><code>MYSET</code></em>.c</code>
        source file in the <code class="filename">strings</code> directory.
      </p><p>
        The existing character sets provide the best documentation and
        examples to show how these functions are implemented. Look at
        the <code class="filename">ctype-*.c</code> files in the
        <code class="filename">strings</code> directory, such as the files for
        the <code class="literal">big5</code>, <code class="literal">czech</code>,
        <code class="literal">gbk</code>, <code class="literal">sjis</code>, and
        <code class="literal">tis160</code> character sets. Take a look at the
        <code class="literal">MY_COLLATION_HANDLER</code> structures to see how
        they are used. See also the
        <code class="filename">CHARSET_INFO.txt</code> file in the
        <code class="filename">strings</code> directory for additional
        information.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="multibyte-characters"></a>10.12.3 Multi-Byte Character Support for Complex Character Sets</h3>

</div>

</div>

</div>
<a class="indexterm" name="idm140091695509168"></a><a class="indexterm" name="idm140091695507712"></a><p>
        If you want to add support for a new character set named
        <em class="replaceable"><code>MYSET</code></em> that includes multibyte
        characters, you must use multibyte character functions in the
        <code class="filename">ctype-<em class="replaceable"><code>MYSET</code></em>.c</code>
        source file in the <code class="filename">strings</code> directory.
      </p><p>
        The existing character sets provide the best documentation and
        examples to show how these functions are implemented. Look at
        the <code class="filename">ctype-*.c</code> files in the
        <code class="filename">strings</code> directory, such as the files for
        the <code class="literal">euc_kr</code>, <code class="literal">gb2312</code>,
        <code class="literal">gbk</code>, <code class="literal">sjis</code>, and
        <code class="literal">ujis</code> character sets. Take a look at the
        <code class="literal">MY_CHARSET_HANDLER</code> structures to see how they
        are used. See also the <code class="filename">CHARSET_INFO.txt</code>
        file in the <code class="filename">strings</code> directory for
        additional information.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both"><a name="adding-collation"></a>10.13 Adding a Collation to a Character Set</h2>

</div>

</div>

</div>
<div class="toc">
<dl class="toc"><dt><span class="section"><a href="charset.html#charset-collation-implementations">10.13.1 Collation Implementation Types</a></span></dt><dt><span class="section"><a href="charset.html#adding-collation-choosing-id">10.13.2 Choosing a Collation ID</a></span></dt><dt><span class="section"><a href="charset.html#adding-collation-simple-8bit">10.13.3 Adding a Simple Collation to an 8-Bit Character Set</a></span></dt><dt><span class="section"><a href="charset.html#adding-collation-unicode-uca">10.13.4 Adding a UCA Collation to a Unicode Character Set</a></span></dt></dl>
</div>
<a class="indexterm" name="idm140091695494496"></a><p>
      A collation is a set of rules that defines how to compare and sort
      character strings. Each collation in MySQL belongs to a single
      character set. Every character set has at least one collation, and
      most have two or more collations.
    </p><p>
      A collation orders characters based on weights. Each character in
      a character set maps to a weight. Characters with equal weights
      compare as equal, and characters with unequal weights compare
      according to the relative magnitude of their weights.
    </p><p>
      The <a class="link" href="functions.html#function_weight-string"><code class="literal">WEIGHT_STRING()</code></a> function can be
      used to see the weights for the characters in a string. The value
      that it returns to indicate weights is a binary string, so it is
      convenient to use
      <code class="literal">HEX(WEIGHT_STRING(<em class="replaceable"><code>str</code></em>))</code>
      to display the weights in printable form. The following example
      shows that weights do not differ for lettercase for the letters in
      <code class="literal">'AaBb'</code> if it is a nonbinary case-insensitive
      string, but do differ if it is a binary string:
    </p><pre data-lang="sql" class="programlisting">
mysql&gt; <strong class="userinput"><code>SELECT HEX(WEIGHT_STRING('AaBb' COLLATE latin1_swedish_ci));</code></strong>
+------------------------------------------------------+
| HEX(WEIGHT_STRING('AaBb' COLLATE latin1_swedish_ci)) |
+------------------------------------------------------+
| 41414242                                             |
+------------------------------------------------------+
mysql&gt; <strong class="userinput"><code>SELECT HEX(WEIGHT_STRING(BINARY 'AaBb'));</code></strong>
+-----------------------------------+
| HEX(WEIGHT_STRING(BINARY 'AaBb')) |
+-----------------------------------+
| 41614262                          |
+-----------------------------------+
</pre><p>
      MySQL supports several collation implementations, as discussed in
      <a class="xref" href="charset.html#charset-collation-implementations" title="10.13.1 Collation Implementation Types">Section 10.13.1, “Collation Implementation Types”</a>. Some of these
      can be added to MySQL without recompiling:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          Simple collations for 8-bit character sets.
        </p></li><li class="listitem"><p>
          UCA-based collations for Unicode character sets.
        </p></li><li class="listitem"><p>
          Binary (<code class="literal"><em class="replaceable"><code>xxx</code></em>_bin</code>)
          collations.
</p></li></ul>
</div>
<p>
      The following sections describe how to add collations of the first
      two types to existing character sets. All existing character sets
      already have a binary collation, so there is no need here to
      describe how to add one.
    </p><p>
      Summary of the procedure for adding a new collation:
</p>
<div class="orderedlist">
<ol class="orderedlist" type="1"><li class="listitem"><p>
          Choose a collation ID.
        </p></li><li class="listitem"><p>
          Add configuration information that names the collation and
          describes the character-ordering rules.
        </p></li><li class="listitem"><p>
          Restart the server.
        </p></li><li class="listitem"><p>
          Verify that the collation is present.
</p></li></ol>
</div>
<p>
      The instructions here cover only collations that can be added
      without recompiling MySQL. To add a collation that does require
      recompiling (as implemented by means of functions in a C source
      file), use the instructions in
      <a class="xref" href="charset.html#adding-character-set" title="10.12 Adding a Character Set">Section 10.12, “Adding a Character Set”</a>. However, instead of adding
      all the information required for a complete character set, just
      modify the appropriate files for an existing character set. That
      is, based on what is already present for the character set's
      current collations, add data structures, functions, and
      configuration information for the new collation.
</p><a class="indexterm" name="idm140091695472112"></a>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Note
</div>
<p>
        If you modify an existing collation, that may affect the
        ordering of rows for indexes on columns that use the collation.
        In this case, rebuild any such indexes to avoid problems such as
        incorrect query results. See
        <a class="xref" href="installing.html#rebuilding-tables" title="2.11.13 Rebuilding or Repairing Tables or Indexes">Section 2.11.13, “Rebuilding or Repairing Tables or Indexes”</a>.
</p>
</div>
<h3><a name="idm140091695468944"></a>Additional Resources</h3>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          The Unicode Collation Algorithm (UCA) specification:
          <a class="ulink" href="http://www.unicode.org/reports/tr10/" target="_top">http://www.unicode.org/reports/tr10/</a>
        </p></li><li class="listitem"><p>
          The Locale Data Markup Language (LDML) specification:
          <a class="ulink" href="http://www.unicode.org/reports/tr35/" target="_top">http://www.unicode.org/reports/tr35/</a>
</p></li></ul>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="charset-collation-implementations"></a>10.13.1 Collation Implementation Types</h3>

</div>

</div>

</div>
<p>
        MySQL implements several types of collations:
      </p><p>
        <span class="bold"><strong>Simple collations for 8-bit character
        sets</strong></span>
      </p><p>
        This kind of collation is implemented using an array of 256
        weights that defines a one-to-one mapping from character codes
        to weights. <code class="literal">latin1_swedish_ci</code> is an example.
        It is a case-insensitive collation, so the uppercase and
        lowercase versions of a character have the same weights and they
        compare as equal.
      </p><pre data-lang="sql" class="programlisting">
mysql&gt; <strong class="userinput"><code>SET NAMES 'latin1' COLLATE 'latin1_swedish_ci';</code></strong>
Query OK, 0 rows affected (0.01 sec)

mysql&gt; <strong class="userinput"><code>SELECT HEX(WEIGHT_STRING('a')), HEX(WEIGHT_STRING('A'));</code></strong>
+-------------------------+-------------------------+
| HEX(WEIGHT_STRING('a')) | HEX(WEIGHT_STRING('A')) |
+-------------------------+-------------------------+
| 41                      | 41                      |
+-------------------------+-------------------------+
1 row in set (0.01 sec)

mysql&gt; <strong class="userinput"><code>SELECT 'a' = 'A';</code></strong>
+-----------+
| 'a' = 'A' |
+-----------+
|         1 |
+-----------+
1 row in set (0.12 sec)
</pre><p>
        For implementation instructions, see
        <a class="xref" href="charset.html#adding-collation-simple-8bit" title="10.13.3 Adding a Simple Collation to an 8-Bit Character Set">Section 10.13.3, “Adding a Simple Collation to an 8-Bit Character Set”</a>.
      </p><p>
        <span class="bold"><strong>Complex collations for 8-bit character
        sets</strong></span>
      </p><p>
        This kind of collation is implemented using functions in a C
        source file that define how to order characters, as described in
        <a class="xref" href="charset.html#adding-character-set" title="10.12 Adding a Character Set">Section 10.12, “Adding a Character Set”</a>.
      </p><p>
        <span class="bold"><strong>Collations for non-Unicode multibyte
        character sets</strong></span>
      </p><p>
        For this type of collation, 8-bit (single-byte) and multibyte
        characters are handled differently. For 8-bit characters,
        character codes map to weights in case-insensitive fashion. (For
        example, the single-byte characters <code class="literal">'a'</code> and
        <code class="literal">'A'</code> both have a weight of
        <code class="literal">0x41</code>.) For multibyte characters, there are
        two types of relationship between character codes and weights:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            Weights equal character codes.
            <code class="literal">sjis_japanese_ci</code> is an example of this
            kind of collation. The multibyte character
            <code class="literal">'ぢ'</code> has a character code of
            <code class="literal">0x82C0</code>, and the weight is also
            <code class="literal">0x82C0</code>.
          </p><pre data-lang="sql" class="programlisting">
mysql&gt; <strong class="userinput"><code>CREATE TABLE t1</code></strong>
       <strong class="userinput"><code>(c1 VARCHAR(2) CHARACTER SET sjis COLLATE sjis_japanese_ci);</code></strong>
Query OK, 0 rows affected (0.01 sec)

mysql&gt; <strong class="userinput"><code>INSERT INTO t1 VALUES ('a'),('A'),(0x82C0);</code></strong>
Query OK, 3 rows affected (0.00 sec)
Records: 3  Duplicates: 0  Warnings: 0

mysql&gt; <strong class="userinput"><code>SELECT c1, HEX(c1), HEX(WEIGHT_STRING(c1)) FROM t1;</code></strong>
+------+---------+------------------------+
| c1   | HEX(c1) | HEX(WEIGHT_STRING(c1)) |
+------+---------+------------------------+
| a    | 61      | 41                     |
| A    | 41      | 41                     |
| ぢ    | 82C0    | 82C0                   |
+------+---------+------------------------+
3 rows in set (0.00 sec)
</pre></li><li class="listitem"><p>
            Character codes map one-to-one to weights, but a code is not
            necessarily equal to the weight.
            <code class="literal">gbk_chinese_ci</code> is an example of this kind
            of collation. The multibyte character
            <code class="literal">'膰'</code> has a character code of
            <code class="literal">0x81B0</code> but a weight of
            <code class="literal">0xC286</code>.
          </p><pre data-lang="sql" class="programlisting">
mysql&gt; <strong class="userinput"><code>CREATE TABLE t1</code></strong>
       <strong class="userinput"><code>(c1 VARCHAR(2) CHARACTER SET gbk COLLATE gbk_chinese_ci);</code></strong>
Query OK, 0 rows affected (0.33 sec)

mysql&gt; <strong class="userinput"><code>INSERT INTO t1 VALUES ('a'),('A'),(0x81B0);</code></strong>
Query OK, 3 rows affected (0.00 sec)
Records: 3  Duplicates: 0  Warnings: 0

mysql&gt; <strong class="userinput"><code>SELECT c1, HEX(c1), HEX(WEIGHT_STRING(c1)) FROM t1;</code></strong>
+------+---------+------------------------+
| c1   | HEX(c1) | HEX(WEIGHT_STRING(c1)) |
+------+---------+------------------------+
| a    | 61      | 41                     |
| A    | 41      | 41                     |
| 膰    | 81B0    | C286                   |
+------+---------+------------------------+
3 rows in set (0.00 sec)
</pre></li></ul>
</div>
<p>
        For implementation instructions, see
        <a class="xref" href="charset.html#adding-character-set" title="10.12 Adding a Character Set">Section 10.12, “Adding a Character Set”</a>.
      </p><p>
        <span class="bold"><strong>Collations for Unicode multibyte character
        sets</strong></span>
      </p><p>
        Some of these collations are based on the Unicode Collation
        Algorithm (UCA), others are not.
      </p><p>
        Non-UCA collations have a one-to-one mapping from character code
        to weight. In MySQL, such collations are case insensitive and
        accent insensitive. <code class="literal">utf8_general_ci</code> is an
        example: <code class="literal">'a'</code>, <code class="literal">'A'</code>,
        <code class="literal">'À'</code>, and <code class="literal">'á'</code> each have
        different character codes but all have a weight of
        <code class="literal">0x0041</code> and compare as equal.
      </p><pre data-lang="sql" class="programlisting">
mysql&gt; <strong class="userinput"><code>SET NAMES 'utf8' COLLATE 'utf8_general_ci';</code></strong>
Query OK, 0 rows affected (0.00 sec)

mysql&gt; <strong class="userinput"><code>CREATE TABLE t1</code></strong>
       <strong class="userinput"><code>(c1 CHAR(1) CHARACTER SET UTF8 COLLATE utf8_general_ci);</code></strong>
Query OK, 0 rows affected (0.01 sec)

mysql&gt; <strong class="userinput"><code>INSERT INTO t1 VALUES ('a'),('A'),('À'),('á');</code></strong>
Query OK, 4 rows affected (0.00 sec)
Records: 4  Duplicates: 0  Warnings: 0

mysql&gt; <strong class="userinput"><code>SELECT c1, HEX(c1), HEX(WEIGHT_STRING(c1)) FROM t1;</code></strong>
+------+---------+------------------------+
| c1   | HEX(c1) | HEX(WEIGHT_STRING(c1)) |
+------+---------+------------------------+
| a    | 61      | 0041                   |
| A    | 41      | 0041                   |
| À    | C380    | 0041                   |
| á    | C3A1    | 0041                   |
+------+---------+------------------------+
4 rows in set (0.00 sec)
</pre><p>
        UCA-based collations in MySQL have these properties:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            If a character has weights, each weight uses 2 bytes (16
            bits).
          </p></li><li class="listitem"><p>
            A character may have zero weights (or an empty weight). In
            this case, the character is ignorable. Example: "U+0000
            NULL" does not have a weight and is ignorable.
          </p></li><li class="listitem"><p>
            A character may have one weight. Example:
            <code class="literal">'a'</code> has a weight of
            <code class="literal">0x0E33</code>.
          </p><pre data-lang="sql" class="programlisting">
mysql&gt; <strong class="userinput"><code>SET NAMES 'utf8' COLLATE 'utf8_unicode_ci';</code></strong>
Query OK, 0 rows affected (0.05 sec)

mysql&gt; <strong class="userinput"><code>SELECT HEX('a'), HEX(WEIGHT_STRING('a'));</code></strong>
+----------+-------------------------+
| HEX('a') | HEX(WEIGHT_STRING('a')) |
+----------+-------------------------+
| 61       | 0E33                    |
+----------+-------------------------+
1 row in set (0.02 sec)
</pre></li><li class="listitem"><p>
            A character may have many weights. This is an expansion.
            Example: The German letter <code class="literal">'ß'</code> (SZ
            ligature, or SHARP S) has a weight of
            <code class="literal">0x0FEA0FEA</code>.
          </p><pre data-lang="sql" class="programlisting">
mysql&gt; <strong class="userinput"><code>SET NAMES 'utf8' COLLATE 'utf8_unicode_ci';</code></strong>
Query OK, 0 rows affected (0.11 sec)

mysql&gt; <strong class="userinput"><code>SELECT HEX('ß'), HEX(WEIGHT_STRING('ß'));</code></strong>
+-----------+--------------------------+
| HEX('ß')  | HEX(WEIGHT_STRING('ß'))  |
+-----------+--------------------------+
| C39F      | 0FEA0FEA                 |
+-----------+--------------------------+
1 row in set (0.00 sec)
</pre></li><li class="listitem"><p>
            Many characters may have one weight. This is a contraction.
            Example: <code class="literal">'ch'</code> is a single letter in Czech
            and has a weight of <code class="literal">0x0EE2</code>.
          </p><pre data-lang="sql" class="programlisting">
mysql&gt; <strong class="userinput"><code>SET NAMES 'utf8' COLLATE 'utf8_czech_ci';</code></strong>
Query OK, 0 rows affected (0.09 sec)

mysql&gt; <strong class="userinput"><code>SELECT HEX('ch'), HEX(WEIGHT_STRING('ch'));</code></strong>
+-----------+--------------------------+
| HEX('ch') | HEX(WEIGHT_STRING('ch')) |
+-----------+--------------------------+
| 6368      | 0EE2                     |
+-----------+--------------------------+
1 row in set (0.00 sec)
</pre></li></ul>
</div>
<p>
        A many-characters-to-many-weights mapping is also possible (this
        is contraction with expansion), but is not supported by MySQL.
      </p><p>
        For implementation instructions, for a non-UCA collation, see
        <a class="xref" href="charset.html#adding-character-set" title="10.12 Adding a Character Set">Section 10.12, “Adding a Character Set”</a>. For a UCA collation, see
        <a class="xref" href="charset.html#adding-collation-unicode-uca" title="10.13.4 Adding a UCA Collation to a Unicode Character Set">Section 10.13.4, “Adding a UCA Collation to a Unicode Character Set”</a>.
      </p><p>
        <span class="bold"><strong>Miscellaneous collations</strong></span>
      </p><p>
        There are also a few collations that do not fall into any of the
        previous categories.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="adding-collation-choosing-id"></a>10.13.2 Choosing a Collation ID</h3>

</div>

</div>

</div>
<p>
        Each collation must have a unique ID. To add a collation, you
        must choose an ID value that is not currently used. MySQL
        supports two-byte collation IDs. The range of IDs from 1024 to
        2047 is reserved for user-defined collations. The collation ID
        that you choose will appear in these contexts:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            The <code class="literal">ID</code> column of the
            <a class="link" href="information-schema.html#collations-table" title="25.4 The INFORMATION_SCHEMA COLLATIONS Table"><code class="literal">INFORMATION_SCHEMA.COLLATIONS</code></a>
            table.
          </p></li><li class="listitem"><p>
            The <code class="literal">Id</code> column of
            <a class="link" href="sql-syntax.html#show-collation" title="13.7.6.4 SHOW COLLATION Syntax"><code class="literal">SHOW COLLATION</code></a> output.
          </p></li><li class="listitem"><p>
            The <code class="literal">charsetnr</code> member of the
            <code class="literal">MYSQL_FIELD</code> C API data structure.
          </p></li><li class="listitem"><p>
            The <code class="literal">number</code> member of the
            <code class="literal">MY_CHARSET_INFO</code> data structure returned
            by the
            <a class="link" href="connectors-apis.html#mysql-get-character-set-info" title="28.7.7.26 mysql_get_character_set_info()"><code class="literal">mysql_get_character_set_info()</code></a>
            C API function.
</p></li></ul>
</div>
<p>
        To determine the largest currently used ID, issue the following
        statement:
      </p><pre data-lang="sql" class="programlisting">
mysql&gt; <strong class="userinput"><code>SELECT MAX(ID) FROM INFORMATION_SCHEMA.COLLATIONS;</code></strong>
+---------+
| MAX(ID) |
+---------+
|     210 |
+---------+
</pre><p>
        To display a list of all currently used IDs, issue this
        statement:
      </p><pre data-lang="sql" class="programlisting">
mysql&gt; <strong class="userinput"><code>SELECT ID FROM INFORMATION_SCHEMA.COLLATIONS ORDER BY ID;</code></strong>
+-----+
| ID  |
+-----+
|   1 |
|   2 |
| ... |
|  52 |
|  53 |
|  57 |
|  58 |
| ... |
|  98 |
|  99 |
| 128 |
| 129 |
| ... |
| 210 |
+-----+
</pre>
<div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Warning
</div>
<p>
          Before upgrading, you should save the configuration files that
          you change. If you upgrade in place, the process will replace
          the your modified files.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="adding-collation-simple-8bit"></a>10.13.3 Adding a Simple Collation to an 8-Bit Character Set</h3>

</div>

</div>

</div>
<p>
        This section describes how to add a simple collation for an
        8-bit character set by writing the
        <code class="literal">&lt;collation&gt;</code> elements associated with a
        <code class="literal">&lt;charset&gt;</code> character set description in
        the MySQL <code class="filename">Index.xml</code> file. The procedure
        described here does not require recompiling MySQL. The example
        adds a collation named <code class="literal">latin1_test_ci</code> to the
        <code class="literal">latin1</code> character set.
</p>
<div class="orderedlist">
<ol class="orderedlist" type="1"><li class="listitem"><p>
            Choose a collation ID, as shown in
            <a class="xref" href="charset.html#adding-collation-choosing-id" title="10.13.2 Choosing a Collation ID">Section 10.13.2, “Choosing a Collation ID”</a>. The
            following steps use an ID of 1024.
          </p></li><li class="listitem"><p>
            Modify the <code class="literal">Index.xml</code> and
            <code class="literal">latin1.xml</code> configuration files. These
            files are located in the directory named by the
            <a class="link" href="server-administration.html#sysvar_character_sets_dir"><code class="literal">character_sets_dir</code></a> system
            variable. You can check the variable value as follows,
            although the path name might be different on your system:
          </p><pre data-lang="sql" class="programlisting">
mysql&gt; <strong class="userinput"><code>SHOW VARIABLES LIKE 'character_sets_dir';</code></strong>
+--------------------+-----------------------------------------+
| Variable_name      | Value                                   |
+--------------------+-----------------------------------------+
| character_sets_dir | /user/local/mysql/share/mysql/charsets/ |
+--------------------+-----------------------------------------+
</pre></li><li class="listitem"><p>
            Choose a name for the collation and list it in the
            <code class="filename">Index.xml</code> file. Find the
            <code class="literal">&lt;charset&gt;</code> element for the character
            set to which the collation is being added, and add a
            <code class="literal">&lt;collation&gt;</code> element that indicates
            the collation name and ID, to associate the name with the
            ID. For example:
          </p><pre data-lang="xml" class="programlisting">
&lt;charset name="latin1"&gt;
  ...
  &lt;collation name="latin1_test_ci" id="1024"/&gt;
  ...
&lt;/charset&gt;
</pre></li><li class="listitem"><p>
            In the <code class="filename">latin1.xml</code> configuration file,
            add a <code class="literal">&lt;collation&gt;</code> element that
            names the collation and that contains a
            <code class="literal">&lt;map&gt;</code> element that defines a
            character code-to-weight mapping table for character codes 0
            to 255. Each value within the <code class="literal">&lt;map&gt;</code>
            element must be a number in hexadecimal format.
          </p><pre data-lang="xml" class="programlisting">
&lt;collation name="latin1_test_ci"&gt;
&lt;map&gt;
 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
 10 11 12 13 14 15 16 17 18 19 1A 1B 1C 1D 1E 1F
 20 21 22 23 24 25 26 27 28 29 2A 2B 2C 2D 2E 2F
 30 31 32 33 34 35 36 37 38 39 3A 3B 3C 3D 3E 3F
 40 41 42 43 44 45 46 47 48 49 4A 4B 4C 4D 4E 4F
 50 51 52 53 54 55 56 57 58 59 5A 5B 5C 5D 5E 5F
 60 41 42 43 44 45 46 47 48 49 4A 4B 4C 4D 4E 4F
 50 51 52 53 54 55 56 57 58 59 5A 7B 7C 7D 7E 7F
 80 81 82 83 84 85 86 87 88 89 8A 8B 8C 8D 8E 8F
 90 91 92 93 94 95 96 97 98 99 9A 9B 9C 9D 9E 9F
 A0 A1 A2 A3 A4 A5 A6 A7 A8 A9 AA AB AC AD AE AF
 B0 B1 B2 B3 B4 B5 B6 B7 B8 B9 BA BB BC BD BE BF
 41 41 41 41 5B 5D 5B 43 45 45 45 45 49 49 49 49
 44 4E 4F 4F 4F 4F 5C D7 5C 55 55 55 59 59 DE DF
 41 41 41 41 5B 5D 5B 43 45 45 45 45 49 49 49 49
 44 4E 4F 4F 4F 4F 5C F7 5C 55 55 55 59 59 DE FF
&lt;/map&gt;
&lt;/collation&gt;
</pre></li><li class="listitem"><p>
            Restart the server and use this statement to verify that the
            collation is present:
          </p><pre data-lang="sql" class="programlisting">
mysql&gt; <strong class="userinput"><code>SHOW COLLATION WHERE Collation = 'latin1_test_ci';</code></strong>
+----------------+---------+------+---------+----------+---------+
| Collation      | Charset | Id   | Default | Compiled | Sortlen |
+----------------+---------+------+---------+----------+---------+
| latin1_test_ci | latin1  | 1024 |         |          |       1 |
+----------------+---------+------+---------+----------+---------+
</pre></li></ol>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="adding-collation-unicode-uca"></a>10.13.4 Adding a UCA Collation to a Unicode Character Set</h3>

</div>

</div>

</div>
<div class="toc">
<dl class="toc"><dt><span class="section"><a href="charset.html#ldml-collation-example">10.13.4.1 Defining a UCA Collation Using LDML Syntax</a></span></dt><dt><span class="section"><a href="charset.html#ldml-rules">10.13.4.2 LDML Syntax Supported in MySQL</a></span></dt><dt><span class="section"><a href="charset.html#collation-diagnostics">10.13.4.3 Diagnostics During Index.xml Parsing</a></span></dt></dl>
</div>
<p>
        This section describes how to add a UCA collation for a Unicode
        character set by writing the
        <code class="literal">&lt;collation&gt;</code> element within a
        <code class="literal">&lt;charset&gt;</code> character set description in
        the MySQL <code class="filename">Index.xml</code> file. The procedure
        described here does not require recompiling MySQL. It uses a
        subset of the Locale Data Markup Language (LDML) specification,
        which is available at
        <a class="ulink" href="http://www.unicode.org/reports/tr35/" target="_top">http://www.unicode.org/reports/tr35/</a>. With this
        method, you need not define the entire collation. Instead, you
        begin with an existing <span class="quote">“<span class="quote">base</span>”</span> collation and
        describe the new collation in terms of how it differs from the
        base collation. The following table lists the base collations of
        the Unicode character sets for which UCA collations can be
        defined. It is not possible to create user-defined UCA
        collations for <code class="literal">utf16le</code>; there is no
        <code class="literal">utf16le_unicode_ci</code> collation that would serve
        as the basis for such collations.
</p>
<div class="table">
<a name="idm140091695340800"></a><p class="title"><b>Table 10.4 MySQL Character Sets Available for User-Defined UCA Collations</b></p>
<div class="table-contents">
<table summary="Unicode character sets for which user-defined UCA collations can be defined and their base collations."><col width="30*"><col width="60*"><thead><tr>
            <th scope="col">Character Set</th>
            <th scope="col">Base Collation</th>
          </tr></thead><tbody><tr>
            <th scope="row" align="left"><code class="literal">utf8</code></th>
            <td><code class="literal">utf8_unicode_ci</code></td>
          </tr><tr>
            <th scope="row" align="left"><code class="literal">ucs2</code></th>
            <td><code class="literal">ucs2_unicode_ci</code></td>
          </tr><tr>
            <th scope="row" align="left"><code class="literal">utf16</code></th>
            <td><code class="literal">utf16_unicode_ci</code></td>
          </tr><tr>
            <th scope="row" align="left"><code class="literal">utf32</code></th>
            <td><code class="literal">utf32_unicode_ci</code></td>
</tr></tbody></table>
</div>

</div>
<br class="table-break"><p>
        The following sections show how to add a collation that is
        defined using LDML syntax, and provide a summary of LDML rules
        supported in MySQL.
</p>
<div class="section">

<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="ldml-collation-example"></a>10.13.4.1 Defining a UCA Collation Using LDML Syntax</h4>
</div>
</div>
</div>
<p>
          To add a UCA collation for a Unicode character set without
          recompiling MySQL, use the following procedure. If you are
          unfamiliar with the LDML rules used to describe the
          collation's sort characteristics, see
          <a class="xref" href="charset.html#ldml-rules" title="10.13.4.2 LDML Syntax Supported in MySQL">Section 10.13.4.2, “LDML Syntax Supported in MySQL”</a>.
        </p><p>
          The example adds a collation named
          <code class="literal">utf8_phone_ci</code> to the
          <code class="literal">utf8</code> character set. The collation is
          designed for a scenario involving a Web application for which
          users post their names and phone numbers. Phone numbers can be
          given in very different formats:
        </p><pre data-lang="none" class="programlisting">
+7-12345-67
+7-12-345-67
+7 12 345 67
+7 (12) 345 67
+71234567
</pre><p>
          The problem raised by dealing with these kinds of values is
          that the varying permissible formats make searching for a
          specific phone number very difficult. The solution is to
          define a new collation that reorders punctuation characters,
          making them ignorable.
</p>
<div class="orderedlist">
<ol class="orderedlist" type="1"><li class="listitem"><p>
              Choose a collation ID, as shown in
              <a class="xref" href="charset.html#adding-collation-choosing-id" title="10.13.2 Choosing a Collation ID">Section 10.13.2, “Choosing a Collation ID”</a>. The
              following steps use an ID of 1029.
            </p></li><li class="listitem"><p>
              To modify the <code class="literal">Index.xml</code> configuration
              file. This file is located in the directory named by the
              <a class="link" href="server-administration.html#sysvar_character_sets_dir"><code class="literal">character_sets_dir</code></a> system
              variable. You can check the variable value as follows,
              although the path name might be different on your system:
            </p><pre data-lang="sql" class="programlisting">
mysql&gt; <strong class="userinput"><code>SHOW VARIABLES LIKE 'character_sets_dir';</code></strong>
+--------------------+-----------------------------------------+
| Variable_name      | Value                                   |
+--------------------+-----------------------------------------+
| character_sets_dir | /user/local/mysql/share/mysql/charsets/ |
+--------------------+-----------------------------------------+
</pre></li><li class="listitem"><p>
              Choose a name for the collation and list it in the
              <code class="filename">Index.xml</code> file. In addition, you'll
              need to provide the collation ordering rules. Find the
              <code class="literal">&lt;charset&gt;</code> element for the
              character set to which the collation is being added, and
              add a <code class="literal">&lt;collation&gt;</code> element that
              indicates the collation name and ID, to associate the name
              with the ID. Within the
              <code class="literal">&lt;collation&gt;</code> element, provide a
              <code class="literal">&lt;rules&gt;</code> element containing the
              ordering rules:
            </p><pre data-lang="xml" class="programlisting">
&lt;charset name="utf8"&gt;
  ...
  &lt;collation name="utf8_phone_ci" id="1029"&gt;
    &lt;rules&gt;
      &lt;reset&gt;\u0000&lt;/reset&gt;
      &lt;i&gt;\u0020&lt;/i&gt; &lt;!-- space --&gt;
      &lt;i&gt;\u0028&lt;/i&gt; &lt;!-- left parenthesis --&gt;
      &lt;i&gt;\u0029&lt;/i&gt; &lt;!-- right parenthesis --&gt;
      &lt;i&gt;\u002B&lt;/i&gt; &lt;!-- plus --&gt;
      &lt;i&gt;\u002D&lt;/i&gt; &lt;!-- hyphen --&gt;
    &lt;/rules&gt;
  &lt;/collation&gt;
  ...
&lt;/charset&gt;
</pre></li><li class="listitem"><p>
              If you want a similar collation for other Unicode
              character sets, add other
              <code class="literal">&lt;collation&gt;</code> elements. For
              example, to define <code class="literal">ucs2_phone_ci</code>, add a
              <code class="literal">&lt;collation&gt;</code> element to the
              <code class="literal">&lt;charset name="ucs2"&gt;</code> element.
              Remember that each collation must have its own unique ID.
            </p></li><li class="listitem"><p>
              Restart the server and use this statement to verify that
              the collation is present:
            </p><pre data-lang="sql" class="programlisting">
mysql&gt; <strong class="userinput"><code>SHOW COLLATION WHERE Collation = 'utf8_phone_ci';</code></strong>
+---------------+---------+------+---------+----------+---------+
| Collation     | Charset | Id   | Default | Compiled | Sortlen |
+---------------+---------+------+---------+----------+---------+
| utf8_phone_ci | utf8    | 1029 |         |          |       8 |
+---------------+---------+------+---------+----------+---------+
</pre></li></ol>
</div>
<p>
          Now test the collation to make sure that it has the desired
          properties.
        </p><p>
          Create a table containing some sample phone numbers using the
          new collation:
        </p><pre data-lang="sql" class="programlisting">
mysql&gt; <strong class="userinput"><code>CREATE TABLE phonebook (</code></strong>
       <strong class="userinput"><code>  name VARCHAR(64),</code></strong>
       <strong class="userinput"><code>  phone VARCHAR(64) CHARACTER SET utf8 COLLATE utf8_phone_ci</code></strong>
       <strong class="userinput"><code>);</code></strong>
Query OK, 0 rows affected (0.09 sec)

mysql&gt; <strong class="userinput"><code>INSERT INTO phonebook VALUES ('Svoj','+7 912 800 80 02');</code></strong>
Query OK, 1 row affected (0.00 sec)

mysql&gt; <strong class="userinput"><code>INSERT INTO phonebook VALUES ('Hf','+7 (912) 800 80 04');</code></strong>
Query OK, 1 row affected (0.00 sec)

mysql&gt; <strong class="userinput"><code>INSERT INTO phonebook VALUES ('Bar','+7-912-800-80-01');</code></strong>
Query OK, 1 row affected (0.00 sec)

mysql&gt; <strong class="userinput"><code>INSERT INTO phonebook VALUES ('Ramil','(7912) 800 80 03');</code></strong>
Query OK, 1 row affected (0.00 sec)

mysql&gt; <strong class="userinput"><code>INSERT INTO phonebook VALUES ('Sanja','+380 (912) 8008005');</code></strong>
Query OK, 1 row affected (0.00 sec)
</pre><p>
          Run some queries to see whether the ignored punctuation
          characters are in fact ignored for comparison and sorting:
        </p><pre data-lang="sql" class="programlisting">
mysql&gt; <strong class="userinput"><code>SELECT * FROM phonebook ORDER BY phone;</code></strong>
+-------+--------------------+
| name  | phone              |
+-------+--------------------+
| Sanja | +380 (912) 8008005 |
| Bar   | +7-912-800-80-01   |
| Svoj  | +7 912 800 80 02   |
| Ramil | (7912) 800 80 03   |
| Hf    | +7 (912) 800 80 04 |
+-------+--------------------+
5 rows in set (0.00 sec)

mysql&gt; <strong class="userinput"><code>SELECT * FROM phonebook WHERE phone='+7(912)800-80-01';</code></strong>
+------+------------------+
| name | phone            |
+------+------------------+
| Bar  | +7-912-800-80-01 |
+------+------------------+
1 row in set (0.00 sec)

mysql&gt; <strong class="userinput"><code>SELECT * FROM phonebook WHERE phone='79128008001';</code></strong>
+------+------------------+
| name | phone            |
+------+------------------+
| Bar  | +7-912-800-80-01 |
+------+------------------+
1 row in set (0.00 sec)

mysql&gt; <strong class="userinput"><code>SELECT * FROM phonebook WHERE phone='7 9 1 2 8 0 0 8 0 0 1';</code></strong>
+------+------------------+
| name | phone            |
+------+------------------+
| Bar  | +7-912-800-80-01 |
+------+------------------+
1 row in set (0.00 sec)
</pre>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="ldml-rules"></a>10.13.4.2 LDML Syntax Supported in MySQL</h4>

</div>

</div>

</div>
<a class="indexterm" name="idm140091695276928"></a><p>
          This section describes the LDML syntax that MySQL recognizes.
          This is a subset of the syntax described in the LDML
          specification available at
          <a class="ulink" href="http://www.unicode.org/reports/tr35/" target="_top">http://www.unicode.org/reports/tr35/</a>, which
          should be consulted for further information. MySQL recognizes
          a large enough subset of the syntax that, in many cases, it is
          possible to download a collation definition from the Unicode
          Common Locale Data Repository and paste the relevant part
          (that is, the part between the
          <code class="literal">&lt;rules&gt;</code> and
          <code class="literal">&lt;/rules&gt;</code> tags) into the MySQL
          <code class="filename">Index.xml</code> file. The rules described here
          are all supported except that character sorting occurs only at
          the primary level. Rules that specify differences at secondary
          or higher sort levels are recognized (and thus can be included
          in collation definitions) but are treated as equality at the
          primary level.
        </p><p>
          The MySQL server generates diagnostics when it finds problems
          while parsing the <code class="filename">Index.xml</code> file. See
          <a class="xref" href="charset.html#collation-diagnostics" title="10.13.4.3 Diagnostics During Index.xml Parsing">Section 10.13.4.3, “Diagnostics During Index.xml Parsing”</a>.
        </p><p>
          <span class="bold"><strong>Character Representation</strong></span>
        </p><p>
          Characters named in LDML rules can be written literally or in
          <code class="literal">\u<em class="replaceable"><code>nnnn</code></em></code> format,
          where <em class="replaceable"><code>nnnn</code></em> is the hexadecimal
          Unicode code point value. For example, <code class="literal">A</code>
          and <code class="literal">á</code> can be written literally or as
          <code class="literal">\u0041</code> and <code class="literal">\u00E1</code>.
          Within hexadecimal values, the digits <code class="literal">A</code>
          through <code class="literal">F</code> are not case-sensitive;
          <code class="literal">\u00E1</code> and <code class="literal">\u00e1</code> are
          equivalent. For UCA 4.0.0 collations, hexadecimal notation can
          be used only for characters in the Basic Multilingual Plane,
          not for characters outside the BMP range of
          <code class="literal">0000</code> to <code class="literal">FFFF</code>. For UCA
          5.2.0 collations, hexadecimal notation can be used for any
          character.
        </p><p>
          The <code class="filename">Index.xml</code> file itself should be
          written using UTF-8 encoding.
        </p><p>
          <span class="bold"><strong>Syntax Rules</strong></span>
        </p><p>
          LDML has reset rules and shift rules to specify character
          ordering. Orderings are given as a set of rules that begin
          with a reset rule that establishes an anchor point, followed
          by shift rules that indicate how characters sort relative to
          the anchor point.
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              A <code class="literal">&lt;reset&gt;</code> rule does not specify
              any ordering in and of itself. Instead, it
              <span class="quote">“<span class="quote">resets</span>”</span> the ordering for subsequent shift
              rules to cause them to be taken in relation to a given
              character. Either of the following rules resets subsequent
              shift rules to be taken in relation to the letter
              <code class="literal">'A'</code>:
            </p><pre data-lang="xml" class="programlisting">
&lt;reset&gt;A&lt;/reset&gt;

&lt;reset&gt;\u0041&lt;/reset&gt;
</pre></li><li class="listitem"><p>
              The <code class="literal">&lt;p&gt;</code>,
              <code class="literal">&lt;s&gt;</code>, and
              <code class="literal">&lt;t&gt;</code> shift rules define primary,
              secondary, and tertiary differences of a character from
              another character:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
                  Use primary differences to distinguish separate
                  letters.
                </p></li><li class="listitem"><p>
                  Use secondary differences to distinguish accent
                  variations.
                </p></li><li class="listitem"><p>
                  Use tertiary differences to distinguish lettercase
                  variations.
</p></li></ul>
</div>
<p>
              Either of these rules specifies a primary shift rule for
              the <code class="literal">'G'</code> character:
            </p><pre data-lang="xml" class="programlisting">
&lt;p&gt;G&lt;/p&gt;

&lt;p&gt;\u0047&lt;/p&gt;
</pre></li><li class="listitem"><p>
              The <code class="literal">&lt;i&gt;</code> shift rule indicates that
              one character sorts identically to another. The following
              rules cause <code class="literal">'b'</code> to sort the same as
              <code class="literal">'a'</code>:
            </p><pre data-lang="xml" class="programlisting">
&lt;reset&gt;a&lt;/reset&gt;
&lt;i&gt;b&lt;/i&gt;
</pre></li><li class="listitem"><p>
              Abbreviated shift syntax specifies multiple shift rules
              using a single pair of tags. The following table shows the
              correspondence between abbreviated syntax rules and the
              equivalent nonabbreviated rules.
</p>
<div class="table">
<a name="abreviated-shift-syntax"></a><p class="title"><b>Table 10.5 Abbreviated Shift Syntax</b></p>
<div class="table-contents">
<table summary="Abbreviated and corresponding nonabbreviated shift syntax rules."><col width="40%"><col width="60%"><thead><tr>
                  <th scope="col">Abbreviated Syntax</th>
                  <th scope="col">Nonabbreviated Syntax</th>
                </tr></thead><tbody><tr>
                  <td scope="row"><code class="literal">&lt;pc&gt;xyz&lt;/pc&gt;</code></td>
                  <td><code class="literal">&lt;p&gt;x&lt;/p&gt;&lt;p&gt;y&lt;/p&gt;&lt;p&gt;z&lt;/p&gt;</code></td>
                </tr><tr>
                  <td scope="row"><code class="literal">&lt;sc&gt;xyz&lt;/sc&gt;</code></td>
                  <td><code class="literal">&lt;s&gt;x&lt;/s&gt;&lt;s&gt;y&lt;/s&gt;&lt;s&gt;z&lt;/s&gt;</code></td>
                </tr><tr>
                  <td scope="row"><code class="literal">&lt;tc&gt;xyz&lt;/tc&gt;</code></td>
                  <td><code class="literal">&lt;t&gt;x&lt;/t&gt;&lt;t&gt;y&lt;/t&gt;&lt;t&gt;z&lt;/t&gt;</code></td>
                </tr><tr>
                  <td scope="row"><code class="literal">&lt;ic&gt;xyz&lt;/ic&gt;</code></td>
                  <td><code class="literal">&lt;i&gt;x&lt;/i&gt;&lt;i&gt;y&lt;/i&gt;&lt;i&gt;z&lt;/i&gt;</code></td>
</tr></tbody></table>
</div>

</div>
<br class="table-break"></li><li class="listitem"><p>
              An expansion is a reset rule that establishes an anchor
              point for a multiple-character sequence. MySQL supports
              expansions 2 to 6 characters long. The following rules put
              <code class="literal">'z'</code> greater at the primary level than
              the sequence of three characters <code class="literal">'abc'</code>:
            </p><pre data-lang="xml" class="programlisting">
&lt;reset&gt;abc&lt;/reset&gt;
&lt;p&gt;z&lt;/p&gt;
</pre></li><li class="listitem"><p>
              A contraction is a shift rule that sorts a
              multiple-character sequence. MySQL supports contractions 2
              to 6 characters long. The following rules put the sequence
              of three characters <code class="literal">'xyz'</code> greater at
              the primary level than <code class="literal">'a'</code>:
            </p><pre data-lang="xml" class="programlisting">
&lt;reset&gt;a&lt;/reset&gt;
&lt;p&gt;xyz&lt;/p&gt;
</pre></li><li class="listitem"><p>
              Long expansions and long contractions can be used
              together. These rules put the sequence of three characters
              <code class="literal">'xyz'</code> greater at the primary level than
              the sequence of three characters <code class="literal">'abc'</code>:
            </p><pre data-lang="xml" class="programlisting">
&lt;reset&gt;abc&lt;/reset&gt;
&lt;p&gt;xyz&lt;/p&gt;
</pre></li><li class="listitem"><p>
              Normal expansion syntax uses <code class="literal">&lt;x&gt;</code>
              plus <code class="literal">&lt;extend&gt;</code> elements to specify
              an expansion. The following rules put the character
              <code class="literal">'k'</code> greater at the secondary level than
              the sequence <code class="literal">'ch'</code>. That is,
              <code class="literal">'k'</code> behaves as if it expands to a
              character after <code class="literal">'c'</code> followed by
              <code class="literal">'h'</code>:
            </p><pre data-lang="xml" class="programlisting">
&lt;reset&gt;c&lt;/reset&gt;
&lt;x&gt;&lt;s&gt;k&lt;/s&gt;&lt;extend&gt;h&lt;/extend&gt;&lt;/x&gt;
</pre><p>
              This syntax permits long sequences. These rules sort the
              sequence <code class="literal">'ccs'</code> greater at the tertiary
              level than the sequence <code class="literal">'cscs'</code>:
            </p><pre data-lang="xml" class="programlisting">
&lt;reset&gt;cs&lt;/reset&gt;
&lt;x&gt;&lt;t&gt;ccs&lt;/t&gt;&lt;extend&gt;cs&lt;/extend&gt;&lt;/x&gt;
</pre><p>
              The LDML specification describes normal expansion syntax
              as <span class="quote">“<span class="quote">tricky.</span>”</span> See that specification for
              details.
            </p></li><li class="listitem"><p>
              Previous context syntax uses <code class="literal">&lt;x&gt;</code>
              plus <code class="literal">&lt;context&gt;</code> elements to
              specify that the context before a character affects how it
              sorts. The following rules put <code class="literal">'-'</code>
              greater at the secondary level than
              <code class="literal">'a'</code>, but only when
              <code class="literal">'-'</code> occurs after
              <code class="literal">'b'</code>:
            </p><pre data-lang="xml" class="programlisting">
&lt;reset&gt;a&lt;/reset&gt;
&lt;x&gt;&lt;context&gt;b&lt;/context&gt;&lt;s&gt;-&lt;/s&gt;&lt;/x&gt;
</pre></li><li class="listitem"><p>
              Previous context syntax can include the
              <code class="literal">&lt;extend&gt;</code> element. These rules put
              <code class="literal">'def'</code> greater at the primary level than
              <code class="literal">'aghi'</code>, but only when
              <code class="literal">'def'</code> comes after
              <code class="literal">'abc'</code>:
            </p><pre data-lang="xml" class="programlisting">
&lt;reset&gt;a&lt;/reset&gt;
&lt;x&gt;&lt;context&gt;abc&lt;/context&gt;&lt;p&gt;def&lt;/p&gt;&lt;extend&gt;ghi&lt;/extend&gt;&lt;/x&gt;
</pre></li><li class="listitem"><p>
              Reset rules permit a <code class="literal">before</code> attribute.
              Normally, shift rules after a reset rule indicate
              characters that sort after the reset character. Shift
              rules after a reset rule that has the
              <code class="literal">before</code> attribute indicate characters
              that sort before the reset character. The following rules
              put the character <code class="literal">'b'</code> immediately
              before <code class="literal">'a'</code> at the primary level:
            </p><pre data-lang="xml" class="programlisting">
&lt;reset before="primary"&gt;a&lt;/reset&gt;
&lt;p&gt;b&lt;/p&gt;
</pre><p>
              Permissible <code class="literal">before</code> attribute values
              specify the sort level by name or the equivalent numeric
              value:
            </p><pre data-lang="xml" class="programlisting">
&lt;reset before="primary"&gt;
&lt;reset before="1"&gt;

&lt;reset before="secondary"&gt;
&lt;reset before="2"&gt;

&lt;reset before="tertiary"&gt;
&lt;reset before="3"&gt;
</pre></li><li class="listitem"><p>
              A reset rule can name a logical reset position rather than
              a literal character:
            </p><pre data-lang="xml" class="programlisting">
&lt;first_tertiary_ignorable/&gt;
&lt;last_tertiary_ignorable/&gt;
&lt;first_secondary_ignorable/&gt;
&lt;last_secondary_ignorable/&gt;
&lt;first_primary_ignorable/&gt;
&lt;last_primary_ignorable/&gt;
&lt;first_variable/&gt;
&lt;last_variable/&gt;
&lt;first_non_ignorable/&gt;
&lt;last_non_ignorable/&gt;
&lt;first_trailing/&gt;
&lt;last_trailing/&gt;
</pre><p>
              These rules put <code class="literal">'z'</code> greater at the
              primary level than nonignorable characters that have a
              Default Unicode Collation Element Table (DUCET) entry and
              that are not CJK:
            </p><pre data-lang="xml" class="programlisting">
&lt;reset&gt;&lt;last_non_ignorable/&gt;&lt;/reset&gt;
&lt;p&gt;z&lt;/p&gt;
</pre><p>
              Logical positions have the code points shown in the
              following table.
</p>
<div class="table">
<a name="logical-reset-position-code-points"></a><p class="title"><b>Table 10.6 Logical Reset Position Code Points</b></p>
<div class="table-contents">
<table summary="Logical positions and Unicode 4.0.0 and Unicode 5.2.0 code points."><col width="40%"><col width="30%"><col width="30%"><thead><tr>
                  <th scope="col">Logical Position</th>
                  <th scope="col">Unicode 4.0.0 Code Point</th>
                  <th scope="col">Unicode 5.2.0 Code Point</th>
                </tr></thead><tbody><tr>
                  <td scope="row"><code class="literal">&lt;first_non_ignorable/&gt;</code></td>
                  <td>U+02D0</td>
                  <td>U+02D0</td>
                </tr><tr>
                  <td scope="row"><code class="literal">&lt;last_non_ignorable/&gt;</code></td>
                  <td>U+A48C</td>
                  <td>U+1342E</td>
                </tr><tr>
                  <td scope="row"><code class="literal">&lt;first_primary_ignorable/&gt;</code></td>
                  <td>U+0332</td>
                  <td>U+0332</td>
                </tr><tr>
                  <td scope="row"><code class="literal">&lt;last_primary_ignorable/&gt;</code></td>
                  <td>U+20EA</td>
                  <td>U+101FD</td>
                </tr><tr>
                  <td scope="row"><code class="literal">&lt;first_secondary_ignorable/&gt;</code></td>
                  <td>U+0000</td>
                  <td>U+0000</td>
                </tr><tr>
                  <td scope="row"><code class="literal">&lt;last_secondary_ignorable/&gt;</code></td>
                  <td>U+FE73</td>
                  <td>U+FE73</td>
                </tr><tr>
                  <td scope="row"><code class="literal">&lt;first_tertiary_ignorable/&gt;</code></td>
                  <td>U+0000</td>
                  <td>U+0000</td>
                </tr><tr>
                  <td scope="row"><code class="literal">&lt;last_tertiary_ignorable/&gt;</code></td>
                  <td>U+FE73</td>
                  <td>U+FE73</td>
                </tr><tr>
                  <td scope="row"><code class="literal">&lt;first_trailing/&gt;</code></td>
                  <td>U+0000</td>
                  <td>U+0000</td>
                </tr><tr>
                  <td scope="row"><code class="literal">&lt;last_trailing/&gt;</code></td>
                  <td>U+0000</td>
                  <td>U+0000</td>
                </tr><tr>
                  <td scope="row"><code class="literal">&lt;first_variable/&gt;</code></td>
                  <td>U+0009</td>
                  <td>U+0009</td>
                </tr><tr>
                  <td scope="row"><code class="literal">&lt;last_variable/&gt;</code></td>
                  <td>U+2183</td>
                  <td>U+1D371</td>
</tr></tbody></table>
</div>

</div>
<br class="table-break"></li><li class="listitem"><p>
              The <code class="literal">&lt;collation&gt;</code> element permits a
              <code class="literal">shift-after-method</code> attribute that
              affects character weight calculation for shift rules. The
              attribute has these permitted values:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
                  <code class="literal">simple</code>: Calculate character weights
                  as for reset rules that do not have a
                  <code class="literal">before</code> attribute. This is the
                  default if the attribute is not given.
                </p></li><li class="listitem"><p>
                  <code class="literal">expand</code>: Use expansions for shifts
                  after reset rules.
</p></li></ul>
</div>
<p>
              Suppose that <code class="literal">'0'</code> and
              <code class="literal">'1'</code> have weights of
              <code class="literal">0E29</code> and <code class="literal">0E2A</code> and we
              want to put all basic Latin letters between
              <code class="literal">'0'</code> and <code class="literal">'1'</code>:
            </p><pre data-lang="xml" class="programlisting">
&lt;reset&gt;0&lt;/reset&gt;
&lt;pc&gt;abcdefghijklmnopqrstuvwxyz&lt;/pc&gt;
</pre><p>
              For simple shift mode, weights are calculated as follows:
            </p><pre data-lang="none" class="programlisting">
'a' has weight 0E29+1
'b' has weight 0E29+2
'c' has weight 0E29+3
...
</pre><p>
              However, there are not enough vacant positions to put 26
              characters between <code class="literal">'0'</code> and
              <code class="literal">'1'</code>. The result is that digits and
              letters are intermixed.
            </p><p>
              To solve this, use
              <code class="literal">shift-after-method="expand"</code>. Then
              weights are calculated like this:
            </p><pre data-lang="none" class="programlisting">
'a' has weight [0E29][233D+1]
'b' has weight [0E29][233D+2]
'c' has weight [0E29][233D+3]
...
</pre><p>
              <code class="literal">233D</code> is the UCA 4.0.0 weight for
              character <code class="literal">0xA48C</code>, which is the last
              nonignorable character (a sort of the greatest character
              in the collation, excluding CJK). UCA 5.2.0 is similar but
              uses <code class="literal">3ACA</code>, for character
              <code class="literal">0x1342E</code>.
</p></li></ul>
</div>
<p>
          <span class="bold"><strong>MySQL-Specific LDML
          Extensions</strong></span>
        </p><p>
          An extension to LDML rules permits the
          <code class="literal">&lt;collation&gt;</code> element to include an
          optional <code class="literal">version</code> attribute in
          <code class="literal">&lt;collation&gt;</code> tags to indicate the UCA
          version on which the collation is based. If the
          <code class="literal">version</code> attribute is omitted, its default
          value is <code class="literal">4.0.0</code>. For example, this
          specification indicates a collation that is based on UCA
          5.2.0:
        </p><pre data-lang="xml" class="programlisting">
&lt;collation id="<em class="replaceable"><code>nnn</code></em>" name="utf8_<em class="replaceable"><code>xxx</code></em>_ci" version="5.2.0"&gt;
...
&lt;/collation&gt;
</pre>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="collation-diagnostics"></a>10.13.4.3 Diagnostics During Index.xml Parsing</h4>

</div>

</div>

</div>
<p>
          The MySQL server generates diagnostics when it finds problems
          while parsing the <code class="filename">Index.xml</code> file:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              Unknown tags are written to the error log. For example,
              the following message results if a collation definition
              contains a <code class="literal">&lt;aaa&gt;</code> tag:
            </p><pre data-lang="none" class="programlisting">
[Warning] Buffered warning: Unknown LDML tag:
'charsets/charset/collation/rules/aaa'
</pre></li><li class="listitem"><p>
              If collation initialization is not possible, the server
              reports an <span class="quote">“<span class="quote">Unknown collation</span>”</span> error, and
              also generates warnings explaining the problems, such as
              in the previous example. In other cases, when a collation
              description is generally correct but contains some unknown
              tags, the collation is initialized and is available for
              use. The unknown parts are ignored, but a warning is
              generated in the error log.
            </p></li><li class="listitem"><p>
              Problems with collations generate warnings that clients
              can display with <a class="link" href="sql-syntax.html#show-warnings" title="13.7.6.40 SHOW WARNINGS Syntax"><code class="literal">SHOW
              WARNINGS</code></a>. Suppose that a reset rule contains an
              expansion longer than the maximum supported length of 6
              characters:
            </p><pre data-lang="xml" class="programlisting">
&lt;reset&gt;abcdefghi&lt;/reset&gt;
&lt;i&gt;x&lt;/i&gt;
</pre><p>
              An attempt to use the collation produces warnings:
            </p><pre data-lang="sql" class="programlisting">
mysql&gt; <strong class="userinput"><code>SELECT _utf8'test' COLLATE utf8_test_ci;</code></strong>
ERROR 1273 (HY000): Unknown collation: 'utf8_test_ci'
mysql&gt; <strong class="userinput"><code>SHOW WARNINGS;</code></strong>
+---------+------+----------------------------------------+
| Level   | Code | Message                                |
+---------+------+----------------------------------------+
| Error   | 1273 | Unknown collation: 'utf8_test_ci'      |
| Warning | 1273 | Expansion is too long at 'abcdefghi=x' |
+---------+------+----------------------------------------+
</pre></li></ul>
</div>

</div>

</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both"><a name="charset-configuration"></a>10.14 Character Set Configuration</h2>

</div>

</div>

</div>
<p>
      The MySQL server has a compiled-in default character set and
      collation. To change these defaults, use the
      <a class="link" href="server-administration.html#sysvar_character_set_server"><code class="option">--character-set-server</code></a> and
      <a class="link" href="server-administration.html#sysvar_collation_server"><code class="option">--collation-server</code></a> options when you
      start the server. See <a class="xref" href="server-administration.html#server-options" title="5.1.7 Server Command Options">Section 5.1.7, “Server Command Options”</a>. The
      collation must be a legal collation for the default character set.
      To determine which collations are available for each character
      set, use the <a class="link" href="sql-syntax.html#show-collation" title="13.7.6.4 SHOW COLLATION Syntax"><code class="literal">SHOW COLLATION</code></a>
      statement or query the <code class="literal">INFORMATION_SCHEMA</code>
      <a class="link" href="information-schema.html#collations-table" title="25.4 The INFORMATION_SCHEMA COLLATIONS Table"><code class="literal">COLLATIONS</code></a> table.
    </p><p>
      If you try to use a character set that is not compiled into your
      binary, you might run into the following problems:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          If your program uses an incorrect path to determine where the
          character sets are stored (which is typically the
          <code class="filename">share/mysql/charsets</code> or
          <code class="filename">share/charsets</code> directory under the MySQL
          installation directory), this can be fixed by using the
          <code class="option">--character-sets-dir</code> option when you run the
          program. For example, to specify a directory to be used by
          MySQL client programs, list it in the
          <code class="literal">[client]</code> group of your option file. The
          examples given here show what the setting might look like for
          Unix or Windows, respectively:
        </p><pre data-lang="ini" class="programlisting">
[client]
character-sets-dir=/usr/local/mysql/share/mysql/charsets

[client]
character-sets-dir="C:/Program Files/MySQL/MySQL Server 8.0/share/charsets"
</pre></li><li class="listitem"><p>
          If the character set is a complex character set that cannot be
          loaded dynamically, you must recompile the program with
          support for the character set.
        </p><p>
          For Unicode character sets, you can define collations without
          recompiling by using LDML notation. See
          <a class="xref" href="charset.html#adding-collation-unicode-uca" title="10.13.4 Adding a UCA Collation to a Unicode Character Set">Section 10.13.4, “Adding a UCA Collation to a Unicode Character Set”</a>.
        </p></li><li class="listitem"><p>
          If the character set is a dynamic character set, but you do
          not have a configuration file for it, you should install the
          configuration file for the character set from a new MySQL
          distribution.
        </p></li><li class="listitem"><p>
          If your character set index file
          (<code class="filename">Index.xml</code>) does not contain the name for
          the character set, your program displays an error message:
        </p><pre data-lang="none" class="programlisting">
Character set '<em class="replaceable"><code>charset_name</code></em>' is not a compiled character set and is not
specified in the '/usr/share/mysql/charsets/Index.xml' file
</pre><p>
          To solve this problem, you should either get a new index file
          or manually add the name of any missing character sets to the
          current file.
</p></li></ul>
</div>
<p>
      You can force client programs to use specific character set as
      follows:
    </p><pre data-lang="ini" class="programlisting">
[client]
default-character-set=<em class="replaceable"><code>charset_name</code></em>
</pre><p>
      This is normally unnecessary. However, when
      <a class="link" href="server-administration.html#sysvar_character_set_system"><code class="literal">character_set_system</code></a> differs from
      <a class="link" href="server-administration.html#sysvar_character_set_server"><code class="literal">character_set_server</code></a> or
      <a class="link" href="server-administration.html#sysvar_character_set_client"><code class="literal">character_set_client</code></a>, and you
      input characters manually (as database object identifiers, column
      values, or both), these may be displayed incorrectly in output
      from the client or the output itself may be formatted incorrectly.
      In such cases, starting the mysql client with
      <a class="link" href="programs.html#option_mysql_default-character-set"><code class="option">--default-character-set=<em class="replaceable"><code>system_character_set</code></em></code></a>—that
      is, setting the client character set to match the system character
      set—should fix the problem.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both"><a name="locale-support"></a>10.15 MySQL Server Locale Support</h2>

</div>

</div>

</div>
<p>
      The locale indicated by the
      <a class="link" href="server-administration.html#sysvar_lc_time_names"><code class="literal">lc_time_names</code></a> system variable
      controls the language used to display day and month names and
      abbreviations. This variable affects the output from the
      <a class="link" href="functions.html#function_date-format"><code class="literal">DATE_FORMAT()</code></a>,
      <a class="link" href="functions.html#function_dayname"><code class="literal">DAYNAME()</code></a>, and
      <a class="link" href="functions.html#function_monthname"><code class="literal">MONTHNAME()</code></a> functions.
    </p><p>
      <a class="link" href="server-administration.html#sysvar_lc_time_names"><code class="literal">lc_time_names</code></a> does not affect the
      <a class="link" href="functions.html#function_str-to-date"><code class="literal">STR_TO_DATE()</code></a> or
      <a class="link" href="functions.html#function_get-format"><code class="literal">GET_FORMAT()</code></a> function.
    </p><p>
      The <a class="link" href="server-administration.html#sysvar_lc_time_names"><code class="literal">lc_time_names</code></a> value does not
      affect the result from <a class="link" href="functions.html#function_format"><code class="literal">FORMAT()</code></a>,
      but this function takes an optional third parameter that enables a
      locale to be specified to be used for the result number's decimal
      point, thousands separator, and grouping between separators.
      Permissible locale values are the same as the legal values for the
      <a class="link" href="server-administration.html#sysvar_lc_time_names"><code class="literal">lc_time_names</code></a> system variable.
    </p><p>
      Locale names have language and region subtags listed by IANA
      (<a class="ulink" href="http://www.iana.org/assignments/language-subtag-registry" target="_top">http://www.iana.org/assignments/language-subtag-registry</a>)
      such as <code class="literal">'ja_JP'</code> or <code class="literal">'pt_BR'</code>.
      The default value is <code class="literal">'en_US'</code> regardless of your
      system's locale setting, but you can set the value at server
      startup, or set the <code class="literal">GLOBAL</code> value at runtime if
      you have privileges sufficient to set global system variables; see
      <a class="xref" href="server-administration.html#system-variable-privileges" title="5.1.9.1 System Variable Privileges">Section 5.1.9.1, “System Variable Privileges”</a>. Any client can
      examine the value of
      <a class="link" href="server-administration.html#sysvar_lc_time_names"><code class="literal">lc_time_names</code></a> or set its
      <code class="literal">SESSION</code> value to affect the locale for its own
      connection.
    </p><pre data-lang="sql" class="programlisting">
mysql&gt; <strong class="userinput"><code>SET NAMES 'utf8';</code></strong>
Query OK, 0 rows affected (0.09 sec)

mysql&gt; <strong class="userinput"><code>SELECT @@lc_time_names;</code></strong>
+-----------------+
| @@lc_time_names |
+-----------------+
| en_US           |
+-----------------+
1 row in set (0.00 sec)

mysql&gt; <strong class="userinput"><code>SELECT DAYNAME('2010-01-01'), MONTHNAME('2010-01-01');</code></strong>
+-----------------------+-------------------------+
| DAYNAME('2010-01-01') | MONTHNAME('2010-01-01') |
+-----------------------+-------------------------+
| Friday                | January                 |
+-----------------------+-------------------------+
1 row in set (0.00 sec)

mysql&gt; <strong class="userinput"><code>SELECT DATE_FORMAT('2010-01-01','%W %a %M %b');</code></strong>
+-----------------------------------------+
| DATE_FORMAT('2010-01-01','%W %a %M %b') |
+-----------------------------------------+
| Friday Fri January Jan                  |
+-----------------------------------------+
1 row in set (0.00 sec)

mysql&gt; <strong class="userinput"><code>SET lc_time_names = 'es_MX';</code></strong>
Query OK, 0 rows affected (0.00 sec)

mysql&gt; <strong class="userinput"><code>SELECT @@lc_time_names;</code></strong>
+-----------------+
| @@lc_time_names |
+-----------------+
| es_MX           |
+-----------------+
1 row in set (0.00 sec)

mysql&gt; <strong class="userinput"><code>SELECT DAYNAME('2010-01-01'), MONTHNAME('2010-01-01');</code></strong>
+-----------------------+-------------------------+
| DAYNAME('2010-01-01') | MONTHNAME('2010-01-01') |
+-----------------------+-------------------------+
| viernes               | enero                   |
+-----------------------+-------------------------+
1 row in set (0.00 sec)

mysql&gt; <strong class="userinput"><code>SELECT DATE_FORMAT('2010-01-01','%W %a %M %b');</code></strong>
+-----------------------------------------+
| DATE_FORMAT('2010-01-01','%W %a %M %b') |
+-----------------------------------------+
| viernes vie enero ene                   |
+-----------------------------------------+
1 row in set (0.00 sec)
</pre><p>
      The day or month name for each of the affected functions is
      converted from <code class="literal">utf8</code> to the character set
      indicated by the
      <a class="link" href="server-administration.html#sysvar_character_set_connection"><code class="literal">character_set_connection</code></a> system
      variable.
    </p><p>
      <a class="link" href="server-administration.html#sysvar_lc_time_names"><code class="literal">lc_time_names</code></a> may be set to any
      of the following locale values. The set of locales supported by
      MySQL may differ from those supported by your operating system.
</p>
<div class="informaltable">
<table summary="Locale values to which lc_time_names may be set. The locale values are presented in a two-column table and in alphabetical order from top to bottom."><col width="50%"><col width="50%"><thead><tr>
          <th scope="col">Locale Value</th>
          <th scope="col">Meaning</th>
        </tr></thead><tbody><tr>
          <td scope="row"><code class="literal">ar_AE</code>: Arabic - United Arab Emirates</td>
          <td><code class="literal">ar_BH</code>: Arabic - Bahrain</td>
        </tr><tr>
          <td scope="row"><code class="literal">ar_DZ</code>: Arabic - Algeria</td>
          <td><code class="literal">ar_EG</code>: Arabic - Egypt</td>
        </tr><tr>
          <td scope="row"><code class="literal">ar_IN</code>: Arabic - India</td>
          <td><code class="literal">ar_IQ</code>: Arabic - Iraq</td>
        </tr><tr>
          <td scope="row"><code class="literal">ar_JO</code>: Arabic - Jordan</td>
          <td><code class="literal">ar_KW</code>: Arabic - Kuwait</td>
        </tr><tr>
          <td scope="row"><code class="literal">ar_LB</code>: Arabic - Lebanon</td>
          <td><code class="literal">ar_LY</code>: Arabic - Libya</td>
        </tr><tr>
          <td scope="row"><code class="literal">ar_MA</code>: Arabic - Morocco</td>
          <td><code class="literal">ar_OM</code>: Arabic - Oman</td>
        </tr><tr>
          <td scope="row"><code class="literal">ar_QA</code>: Arabic - Qatar</td>
          <td><code class="literal">ar_SA</code>: Arabic - Saudi Arabia</td>
        </tr><tr>
          <td scope="row"><code class="literal">ar_SD</code>: Arabic - Sudan</td>
          <td><code class="literal">ar_SY</code>: Arabic - Syria</td>
        </tr><tr>
          <td scope="row"><code class="literal">ar_TN</code>: Arabic - Tunisia</td>
          <td><code class="literal">ar_YE</code>: Arabic - Yemen</td>
        </tr><tr>
          <td scope="row"><code class="literal">be_BY</code>: Belarusian - Belarus</td>
          <td><code class="literal">bg_BG</code>: Bulgarian - Bulgaria</td>
        </tr><tr>
          <td scope="row"><code class="literal">ca_ES</code>: Catalan - Spain</td>
          <td><code class="literal">cs_CZ</code>: Czech - Czech Republic</td>
        </tr><tr>
          <td scope="row"><code class="literal">da_DK</code>: Danish - Denmark</td>
          <td><code class="literal">de_AT</code>: German - Austria</td>
        </tr><tr>
          <td scope="row"><code class="literal">de_BE</code>: German - Belgium</td>
          <td><code class="literal">de_CH</code>: German - Switzerland</td>
        </tr><tr>
          <td scope="row"><code class="literal">de_DE</code>: German - Germany</td>
          <td><code class="literal">de_LU</code>: German - Luxembourg</td>
        </tr><tr>
          <td scope="row"><code class="literal">el_GR</code>: Greek - Greece</td>
          <td><code class="literal">en_AU</code>: English - Australia</td>
        </tr><tr>
          <td scope="row"><code class="literal">en_CA</code>: English - Canada</td>
          <td><code class="literal">en_GB</code>: English - United Kingdom</td>
        </tr><tr>
          <td scope="row"><code class="literal">en_IN</code>: English - India</td>
          <td><code class="literal">en_NZ</code>: English - New Zealand</td>
        </tr><tr>
          <td scope="row"><code class="literal">en_PH</code>: English - Philippines</td>
          <td><code class="literal">en_US</code>: English - United States</td>
        </tr><tr>
          <td scope="row"><code class="literal">en_ZA</code>: English - South Africa</td>
          <td><code class="literal">en_ZW</code>: English - Zimbabwe</td>
        </tr><tr>
          <td scope="row"><code class="literal">es_AR</code>: Spanish - Argentina</td>
          <td><code class="literal">es_BO</code>: Spanish - Bolivia</td>
        </tr><tr>
          <td scope="row"><code class="literal">es_CL</code>: Spanish - Chile</td>
          <td><code class="literal">es_CO</code>: Spanish - Colombia</td>
        </tr><tr>
          <td scope="row"><code class="literal">es_CR</code>: Spanish - Costa Rica</td>
          <td><code class="literal">es_DO</code>: Spanish - Dominican Republic</td>
        </tr><tr>
          <td scope="row"><code class="literal">es_EC</code>: Spanish - Ecuador</td>
          <td><code class="literal">es_ES</code>: Spanish - Spain</td>
        </tr><tr>
          <td scope="row"><code class="literal">es_GT</code>: Spanish - Guatemala</td>
          <td><code class="literal">es_HN</code>: Spanish - Honduras</td>
        </tr><tr>
          <td scope="row"><code class="literal">es_MX</code>: Spanish - Mexico</td>
          <td><code class="literal">es_NI</code>: Spanish - Nicaragua</td>
        </tr><tr>
          <td scope="row"><code class="literal">es_PA</code>: Spanish - Panama</td>
          <td><code class="literal">es_PE</code>: Spanish - Peru</td>
        </tr><tr>
          <td scope="row"><code class="literal">es_PR</code>: Spanish - Puerto Rico</td>
          <td><code class="literal">es_PY</code>: Spanish - Paraguay</td>
        </tr><tr>
          <td scope="row"><code class="literal">es_SV</code>: Spanish - El Salvador</td>
          <td><code class="literal">es_US</code>: Spanish - United States</td>
        </tr><tr>
          <td scope="row"><code class="literal">es_UY</code>: Spanish - Uruguay</td>
          <td><code class="literal">es_VE</code>: Spanish - Venezuela</td>
        </tr><tr>
          <td scope="row"><code class="literal">et_EE</code>: Estonian - Estonia</td>
          <td><code class="literal">eu_ES</code>: Basque - Basque</td>
        </tr><tr>
          <td scope="row"><code class="literal">fi_FI</code>: Finnish - Finland</td>
          <td><code class="literal">fo_FO</code>: Faroese - Faroe Islands</td>
        </tr><tr>
          <td scope="row"><code class="literal">fr_BE</code>: French - Belgium</td>
          <td><code class="literal">fr_CA</code>: French - Canada</td>
        </tr><tr>
          <td scope="row"><code class="literal">fr_CH</code>: French - Switzerland</td>
          <td><code class="literal">fr_FR</code>: French - France</td>
        </tr><tr>
          <td scope="row"><code class="literal">fr_LU</code>: French - Luxembourg</td>
          <td><code class="literal">gl_ES</code>: Galician - Spain</td>
        </tr><tr>
          <td scope="row"><code class="literal">gu_IN</code>: Gujarati - India</td>
          <td><code class="literal">he_IL</code>: Hebrew - Israel</td>
        </tr><tr>
          <td scope="row"><code class="literal">hi_IN</code>: Hindi - India</td>
          <td><code class="literal">hr_HR</code>: Croatian - Croatia</td>
        </tr><tr>
          <td scope="row"><code class="literal">hu_HU</code>: Hungarian - Hungary</td>
          <td><code class="literal">id_ID</code>: Indonesian - Indonesia</td>
        </tr><tr>
          <td scope="row"><code class="literal">is_IS</code>: Icelandic - Iceland</td>
          <td><code class="literal">it_CH</code>: Italian - Switzerland</td>
        </tr><tr>
          <td scope="row"><code class="literal">it_IT</code>: Italian - Italy</td>
          <td><code class="literal">ja_JP</code>: Japanese - Japan</td>
        </tr><tr>
          <td scope="row"><code class="literal">ko_KR</code>: Korean - Republic of Korea</td>
          <td><code class="literal">lt_LT</code>: Lithuanian - Lithuania</td>
        </tr><tr>
          <td scope="row"><code class="literal">lv_LV</code>: Latvian - Latvia</td>
          <td><code class="literal">mk_MK</code>: Macedonian - FYROM</td>
        </tr><tr>
          <td scope="row"><code class="literal">mn_MN</code>: Mongolia - Mongolian</td>
          <td><code class="literal">ms_MY</code>: Malay - Malaysia</td>
        </tr><tr>
          <td scope="row"><code class="literal">nb_NO</code>: Norwegian(Bokmål) - Norway</td>
          <td><code class="literal">nl_BE</code>: Dutch - Belgium</td>
        </tr><tr>
          <td scope="row"><code class="literal">nl_NL</code>: Dutch - The Netherlands</td>
          <td><code class="literal">no_NO</code>: Norwegian - Norway</td>
        </tr><tr>
          <td scope="row"><code class="literal">pl_PL</code>: Polish - Poland</td>
          <td><code class="literal">pt_BR</code>: Portugese - Brazil</td>
        </tr><tr>
          <td scope="row"><code class="literal">pt_PT</code>: Portugese - Portugal</td>
          <td><code class="literal">rm_CH</code>: Romansh - Switzerland</td>
        </tr><tr>
          <td scope="row"><code class="literal">ro_RO</code>: Romanian - Romania</td>
          <td><code class="literal">ru_RU</code>: Russian - Russia</td>
        </tr><tr>
          <td scope="row"><code class="literal">ru_UA</code>: Russian - Ukraine</td>
          <td><code class="literal">sk_SK</code>: Slovak - Slovakia</td>
        </tr><tr>
          <td scope="row"><code class="literal">sl_SI</code>: Slovenian - Slovenia</td>
          <td><code class="literal">sq_AL</code>: Albanian - Albania</td>
        </tr><tr>
          <td scope="row"><code class="literal">sr_RS</code>: Serbian - Yugoslavia</td>
          <td><code class="literal">sv_FI</code>: Swedish - Finland</td>
        </tr><tr>
          <td scope="row"><code class="literal">sv_SE</code>: Swedish - Sweden</td>
          <td><code class="literal">ta_IN</code>: Tamil - India</td>
        </tr><tr>
          <td scope="row"><code class="literal">te_IN</code>: Telugu - India</td>
          <td><code class="literal">th_TH</code>: Thai - Thailand</td>
        </tr><tr>
          <td scope="row"><code class="literal">tr_TR</code>: Turkish - Turkey</td>
          <td><code class="literal">uk_UA</code>: Ukrainian - Ukraine</td>
        </tr><tr>
          <td scope="row"><code class="literal">ur_PK</code>: Urdu - Pakistan</td>
          <td><code class="literal">vi_VN</code>: Vietnamese - Viet Nam</td>
        </tr><tr>
          <td scope="row"><code class="literal">zh_CN</code>: Chinese - China</td>
          <td><code class="literal">zh_HK</code>: Chinese - Hong Kong</td>
        </tr><tr>
          <td scope="row"><code class="literal">zh_TW</code>: Chinese - Taiwan Province of China</td>
          <td></td>
</tr></tbody></table>
</div>

</div>

</div>
<div class="copyright-footer">

</div>
<div class="navfooter">
<hr>
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left"><a accesskey="p" href="language-structure.html">Prev</a></td>
<td width="20%" align="center"><a accesskey="u" href="">Up</a></td>
<td width="40%" align="right"> <a accesskey="n" href="data-types.html">Next</a></td>
</tr>
<tr>
<td width="40%" align="left" valign="top">Chapter 9 Language Structure</td>
<td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
<td width="40%" align="right" valign="top">Chapter 11 Data Types</td>
</tr>
</table>
</div>
</body>
</html>
